@yushaw/sanqian-sdk 0.3.27 → 0.3.29

package/README.md

@@ -15,6 +15,8 @@ Sanqian provides two ways to integrate with external applications:
 | **HTTP API** | Simple chat, any language | REST + SSE |
 | **SDK** | Tool registration, agents, context injection, deep integration | WebSocket |
 
+> Documentation baseline: `@yushaw/sanqian-sdk@0.3.28`
+
 ## Quick Start
 
 ### HTTP API
@@ -60,6 +62,15 @@ const sdk = new SanqianSDK({
 
 ---
 
+## Recommended Reading Paths
+
+- Tool integration first-time setup: `Tools` -> `Connection` -> `Browser Build` (if needed)
+- Custom agent workflows: `Agents` -> `Chat` -> `Conversations`
+- Guardrail/intervention flows: `Hooks` -> `Human-in-the-Loop` -> `Security Levels`
+- Channel/chatbot integrations: `Messaging Channels API` -> `Capability Discovery`
+
+---
+
 ## Tools
 
 Tools are the primary way your app provides capabilities to Sanqian. When a user asks a question, the AI agent can call your tools to get data or perform actions.
@@ -341,6 +352,29 @@ const response = await sdk.chat('agent', messages, {
 })
 ```
 
+### Local file ingest
+
+For same-machine deployments where the Sanqian backend can read a local path directly, use `uploadFile()` first, then pass the returned `file.path` into `chat()`:
+
+```typescript
+const uploaded = await sdk.uploadFile('/absolute/path/report.pdf', {
+  conversationId,
+  autoIndex: true,
+  asyncProcess: true,
+})
+
+const response = await sdk.chat('agent', messages, {
+  conversationId: uploaded.conversationId,
+  filePaths: [uploaded.file.path],
+})
+```
+
+`uploadFile(localPath)` is not a remote file transfer protocol. For remote/backend-on-another-machine cases, continue using explicit byte upload APIs.
+
+Conversation targeting contract:
+- If `conversationId` is omitted, backend may create a new SDK conversation and return it in `uploaded.conversationId`.
+- If `conversationId` is provided but does not exist, `uploadFile()` throws `SanqianSDKError` with code `CONVERSATION_NOT_FOUND`.
+
 ---
 
 ## Human-in-the-Loop (HITL)
@@ -581,6 +615,239 @@ sdk.on('resourceRemoved', (resourceId) => {
 
 ---
 
+## Hooks (Available)
+
+> **Status**: Remote hooks are available in the SDK.
+> **Compatibility**: Hook callbacks require a Sanqian backend that supports `register_hook` / `hook_invoke`. On older backends, hook registration may return ack errors and callbacks will not be invoked.
+
+Register hooks to observe or intervene in agent execution. Unlike tools (which the agent calls) and context providers (which inject data), hooks intercept the agent's internal lifecycle -- including prompt ingress, sub-agent lifecycle, model/tool boundaries, and finalization.
+
+### Hook Points
+
+| Hook Point | Type | Description |
+|-----------|------|-------------|
+| `on_user_prompt_submit` | Intervention | User message ingress (can block or rewrite prompt) |
+| `on_stop_failure` | Observation | Run failure classification callback |
+| `on_subagent_start` | Intervention | Before sub-agent starts (can rewrite payload / block) |
+| `on_subagent_stop` | Observation | Sub-agent completion callback |
+| `on_run_start` | Observation | Agent run begins |
+| `on_run_end` | Observation | Agent run ends (success/error) |
+| `on_loop` | Intervention | Each planner loop iteration |
+| `before_model` | Intervention | Before LLM call (can modify prompt) |
+| `after_model` | Intervention | After LLM call (can modify response) |
+| `before_tool` | Intervention | Before tool execution (can block/modify args) |
+| `after_tool` | Intervention | After tool execution (can modify result) |
+| `before_compress` | Intervention | Before context compression |
+| `before_finalize` | Intervention | Before final response is persisted |
+
+### Register Hooks
+
+```typescript
+const sdk = new SanqianSDK({
+  appName: 'my-guardrail',
+  requestedSecurityLevel: 'elevated', // required for before_tool/after_model/before_finalize
+})
+
+// Observe all tool calls (no intervention)
+sdk.registerHook({
+  hookPoints: ['after_tool'],
+  priority: 90,
+}, async (ctx, payload) => {
+  console.log(`Tool ${payload.tool_name}: ${payload.result_status}`)
+  return null // no intervention
+})
+
+// Block dangerous tools
+const hookId = sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: {
+    tool_names: ['delete_file', 'run_bash_command'],
+    args_pattern: { command: 'rm *' }, // optional glob matching on payload fields
+  },
+  priority: 10,
+  failPolicy: 'closed', // if hook is unreachable, block the tool
+}, async (ctx, payload) => {
+  if (isDangerous(payload.tool_args)) {
+    return { decision: 'deny', reason: 'Blocked by safety check' }
+  }
+  return null // allow
+})
+
+// Modify tool args (e.g., inject API key)
+sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: { tool_names: ['web_search'] },
+  priority: 40,
+}, async (ctx, payload) => {
+  return {
+    value: { ...payload.tool_args, api_key: process.env.SEARCH_KEY },
+  }
+})
+
+await sdk.connect()
+
+// Unregister at runtime
+await sdk.unregisterHook(hookId)
+```
+
+Notes:
+- `registerHook()` returns `hookId` immediately and stores registration locally.
+- If already connected, SDK sends `register_hook` asynchronously; transport/ack failures are reported as SDK warnings (non-throwing).
+- For deterministic startup behavior, register hooks before the first `connect()` so declarations are included in initial app registration.
+- `unregisterHook()` is async; use `await` when you need unregister completion before continuing.
+- `unregisterHookAndWait()` waits for `unregister_hook_ack`, throws on nack/timeout, and restores local hook state on failure.
+- `getRegisteredHooks()` returns a defensive snapshot of local hook registrations for diagnostics/audit UIs.
+- `getHookExecutionStats()` returns aggregated runtime hook execution metrics (invocation/success/failure/latency/last error).
+
+Deterministic runtime registration:
+
+```typescript
+const hookId = await sdk.registerHookAndWait({
+  hookPoints: ['before_tool'],
+  failPolicy: 'closed',
+}, async () => null)
+
+await sdk.unregisterHookAndWait(hookId)
+```
+
+- `registerHookAndWait()` waits for `register_hook_ack`.
+- On nack/timeout, it throws and rolls back local registration state.
+- Use this when your app must fail fast on policy wiring errors.
+- `unregisterHookAndWait()` provides the same deterministic behavior for hook teardown.
+
+```typescript
+console.table(sdk.getRegisteredHooks().map((item) => ({
+  hookId: item.hookId,
+  hookPoints: item.registration.hookPoints.join(","),
+  failPolicy: item.registration.failPolicy || "open",
+})))
+
+console.table(sdk.getHookExecutionStats().map((item) => ({
+  hookId: item.hookId,
+  invocations: item.invocationCount,
+  success: item.successCount,
+  failure: item.failureCount,
+  avgMs: Number(item.averageDurationMs.toFixed(2)),
+  lastError: item.lastError || "",
+})))
+```
+
+Typed single-point registration helper:
+
+```typescript
+sdk.registerHookForPoint('before_tool', {
+  matcher: { tool_names: ['run_bash_command'] },
+}, async (_ctx, payload) => {
+  // payload is strongly typed for before_tool
+  return { metadata: { tool: payload.tool_name } }
+})
+
+await sdk.registerHookForPointAndWait('before_tool', {
+  failPolicy: 'closed',
+}, async (_ctx, payload) => {
+  return { decision: payload.tool_name === 'delete_file' ? 'ask' : 'passthrough' }
+})
+```
+
+`payloadValidation` option for typed helpers:
+- `strict` (default): schema mismatch causes hook invocation failure.
+- `warn`: emits SDK `error` event but still calls your handler.
+- `off`: disables runtime schema checks.
+
+Hook roundtrip smoke script:
+
+```bash
+npm --prefix packages/sdk run test:hook-roundtrip-smoke
+```
+
+This script starts a local mock WS backend and verifies all 13 hook points, strict typed payload validation failure path, deterministic unregister (`unregisterHookAndWait`) success/rollback paths, and `hookLifecycle` event emission.
+
+### Hook Actions
+
+Hook handlers return `null` (no intervention) or a `HookResult`:
+
+```typescript
+interface HookResult {
+  skip?: boolean        // Block the operation (e.g., prevent tool execution)
+  value?: unknown       // Replace the value (e.g., modified args or response)
+  suspend?: boolean     // Pause agent, wait for human confirmation
+  suspend_payload?: unknown // Data shown in the HITL confirmation UI
+  metadata?: Record<string, unknown>
+  decision?: 'deny' | 'ask' | 'passthrough' // Structured policy decision
+  reason?: string      // Human-readable reason for deny/ask
+}
+```
+
+Decision precedence on backend aggregation: `deny > ask > passthrough`.
+
+### Suspend (Human-in-the-Loop)
+
+Hooks can pause the agent and wait for external confirmation:
+
+```typescript
+sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: { tool_names: ['send_email'] },
+  priority: 10,
+}, async (ctx, payload) => {
+  // After human confirms, the hook replays with ctx.resume_value
+  if (ctx.resume_value) {
+    return ctx.resume_value.approved ? null : { skip: true }
+  }
+  // First trigger: suspend and show confirmation UI
+  return {
+    suspend: true,
+    suspend_payload: {
+      question: `Allow sending email to ${payload.tool_args.to}?`,
+      preview: JSON.stringify(payload.tool_args).substring(0, 500),
+    },
+  }
+})
+```
+
+### Security Levels
+
+Hook points require minimum security levels:
+
+| Level | Hook Points |
+|-------|-------------|
+| `standard` | on_user_prompt_submit, on_stop_failure, on_subagent_start, on_subagent_stop, on_run_start, on_run_end, on_loop, after_tool, before_compress |
+| `elevated` | before_tool, after_model, before_finalize |
+| `unrestricted` | before_model |
+
+Set `requestedSecurityLevel` in SDKConfig to match the hook points you need.
+
+### Reliability
+
+- **Fail policy**: `"open"` (default) -- hook timeout/error does not block agent. `"closed"` -- hook failure blocks the operation (use for safety-critical hooks).
+- **Timeout**: Differentiated by hook point (tool: 10s, model: 30s, observation: 5s). Override per-hook with `timeout` in registration.
+- **Circuit breaker**: After 5 consecutive failures, the hook is temporarily bypassed (60s recovery).
+
+### Hook Observability Events
+
+```typescript
+sdk.on('hookInvoked', (event) => {
+  console.log(event.hookPoint, event.callId, event.payload)
+})
+
+sdk.on('hookResult', (event) => {
+  console.log(event.hookPoint, event.success, event.durationMs, event.error)
+})
+
+sdk.on('hookLifecycle', (event) => {
+  console.log(
+    event.action,
+    event.hookId,
+    event.success,
+    event.deterministic,
+    event.durationMs,
+    event.error
+  )
+})
+```
+
+---
+
 ## Capability Discovery
 
 Query Sanqian's full capability registry: tools, skills, agents, and context providers.
@@ -755,6 +1022,7 @@ const sdk = new SanqianSDK({
 
   // Display
   displayName: 'My App',           // Shown in Sanqian UI
+  requestedSecurityLevel: 'standard', // Optional: standard | elevated | unrestricted
 
   // Launch
   launchCommand: '/path/to/app',   // For Sanqian to start your app
@@ -777,6 +1045,12 @@ const sdk = new SanqianSDK({
   // Debug
   debug: false,                    // Console logging (default: false)
 
+  // Register handshake (optional; defaults shown)
+  protocolVersion: '2026-03-29',   // Register protocol version (YYYY-MM-DD)
+  hookCapabilities: {              // Hook capability declarations
+    streamingHook: false,          // Negotiated with backend (most-restrictive-wins)
+  },
+
   // Browser mode (see Browser Build section)
   connectionInfo: undefined,       // Pre-configured connection (skips file discovery)
 })
@@ -925,6 +1199,7 @@ console.log(data.message.content)
 ## Built-in Tools Reference
 
 These tools are available to all agents. Use tool names in agent config to enable specific ones, or `["*"]` for all.
+This table is a snapshot. Use `sdk.listTools('builtin')` (or `/api/capabilities`) as runtime source of truth.
 
 ### File Operations
 
@@ -1029,6 +1304,8 @@ Sanqian 提供两种外部集成方式：
 | **HTTP API** | 简单对话，任意语言 | REST + SSE |
 | **SDK** | 工具注册、Agent、上下文注入、深度集成 | WebSocket |
 
+> 文档基线：`@yushaw/sanqian-sdk@0.3.28`
+
 ## 快速开始
 
 ### HTTP API
@@ -1074,6 +1351,15 @@ const sdk = new SanqianSDK({
 
 ---
 
+## 推荐阅读路径
+
+- 第一次做工具集成：`工具 (Tools)` -> `连接` -> `浏览器构建`（如需要）
+- 自定义 Agent 工作流：`Agent` -> `对话 (Chat)` -> `会话管理`
+- 安全干预/护栏：`Hooks` -> `人机协作 (HITL)` -> `安全等级`
+- 渠道机器人接入：`消息渠道 API` -> `能力发现`
+
+---
+
 ## 工具 (Tools)
 
 工具是你的应用向 Sanqian 提供能力的主要方式。当用户提问时，AI Agent 可以调用你的工具来获取数据或执行操作。
@@ -1328,6 +1614,29 @@ const response = await sdk.chat('agent', messages, {
 })
 ```
 
+### 本地文件导入
+
+对于 Sanqian 后端与调用方在同一台机器、且后端能直接读取本地路径的场景，先调用 `uploadFile()`，再把返回的 `file.path` 传给 `chat()`：
+
+```typescript
+const uploaded = await sdk.uploadFile('/absolute/path/report.pdf', {
+  conversationId,
+  autoIndex: true,
+  asyncProcess: true,
+})
+
+const response = await sdk.chat('agent', messages, {
+  conversationId: uploaded.conversationId,
+  filePaths: [uploaded.file.path],
+})
+```
+
+`uploadFile(localPath)` 不是远程文件传输协议。对于远程 backend 或不同机器场景，仍应使用显式字节上传能力。
+
+会话目标契约：
+- 未传 `conversationId` 时，后端可能创建新的 SDK conversation，并通过 `uploaded.conversationId` 返回。
+- 传了 `conversationId` 但该会话不存在时，`uploadFile()` 会抛出 `SanqianSDKError`，错误码为 `CONVERSATION_NOT_FOUND`。
+
 ---
 
 ## 人机协作 (HITL)
@@ -1506,6 +1815,239 @@ for await (const event of sdk.chatStream('agent', messages, {
 
 ---
 
+## Hooks（已可用）
+
+> **状态**: 远程 Hook API 已在 SDK 中可用。
+> **兼容性**: Hook 回调依赖后端支持 `register_hook` / `hook_invoke`。旧版后端可能返回 ack 错误，且不会触发回调。
+
+注册 hooks 来观察或干预 agent 执行。与工具（agent 调用）和上下文提供者（注入数据）不同，hooks 拦截 agent 的内部生命周期，包括用户输入入口、子 agent 生命周期、模型/工具边界和最终收口阶段。
+
+### Hook 点
+
+| Hook 点 | 类型 | 说明 |
+|---------|------|------|
+| `on_user_prompt_submit` | 干预 | 用户消息入口（可拒绝/改写） |
+| `on_stop_failure` | 观察 | 运行失败分类回调 |
+| `on_subagent_start` | 干预 | 子 agent 启动前（可改写 payload / 阻断） |
+| `on_subagent_stop` | 观察 | 子 agent 结束回调 |
+| `on_run_start` | 观察 | Agent run 开始 |
+| `on_run_end` | 观察 | Agent run 结束（成功/错误） |
+| `on_loop` | 干预 | 每轮 planner 循环 |
+| `before_model` | 干预 | LLM 调用前（可修改 prompt） |
+| `after_model` | 干预 | LLM 调用后（可修改响应） |
+| `before_tool` | 干预 | 工具执行前（可阻断/修改参数） |
+| `after_tool` | 干预 | 工具执行后（可修改结果） |
+| `before_compress` | 干预 | 上下文压缩前 |
+| `before_finalize` | 干预 | 最终响应持久化前 |
+
+### 注册 Hooks
+
+```typescript
+const sdk = new SanqianSDK({
+  appName: 'my-guardrail',
+  requestedSecurityLevel: 'elevated', // before_tool/after_model/before_finalize 需要
+})
+
+// 观察所有工具调用（不干预）
+sdk.registerHook({
+  hookPoints: ['after_tool'],
+  priority: 90,
+}, async (ctx, payload) => {
+  console.log(`工具 ${payload.tool_name}: ${payload.result_status}`)
+  return null // 不干预
+})
+
+// 阻断危险工具
+const hookId = sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: {
+    tool_names: ['delete_file', 'run_bash_command'],
+    args_pattern: { command: 'rm *' }, // 可选：按 payload 字段做 glob 匹配
+  },
+  priority: 10,
+  failPolicy: 'closed', // hook 不可达时阻断操作
+}, async (ctx, payload) => {
+  if (isDangerous(payload.tool_args)) {
+    return { decision: 'deny', reason: '安全检查未通过' }
+  }
+  return null // 放行
+})
+
+// 修改工具参数（如注入 API key）
+sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: { tool_names: ['web_search'] },
+  priority: 40,
+}, async (ctx, payload) => {
+  return {
+    value: { ...payload.tool_args, api_key: process.env.SEARCH_KEY },
+  }
+})
+
+await sdk.connect()
+
+// 运行时注销
+await sdk.unregisterHook(hookId)
+```
+
+说明：
+- `registerHook()` 会立即返回 `hookId`，并先在本地登记。
+- 若当前已连接，SDK 会异步发送 `register_hook`；传输/ack 失败仅记录 warning（不会抛出异常）。
+- 若希望启动阶段行为可预测，建议在第一次 `connect()` 前完成 hook 注册，这样会随应用初始注册一并下发。
+- `unregisterHook()` 是异步方法；若后续逻辑依赖注销完成，请使用 `await`。
+- `unregisterHookAndWait()` 会等待 `unregister_hook_ack`；nack/超时时抛错，并回滚本地 hook 状态。
+- `getRegisteredHooks()` 返回本地 hook 注册的防御性快照，可用于诊断/审计界面。
+- `getHookExecutionStats()` 返回运行时 hook 执行聚合指标（调用/成功/失败/耗时/最近错误）。
+
+需要确定性注册时：
+
+```typescript
+const hookId = await sdk.registerHookAndWait({
+  hookPoints: ['before_tool'],
+  failPolicy: 'closed',
+}, async () => null)
+
+await sdk.unregisterHookAndWait(hookId)
+```
+
+- `registerHookAndWait()` 会等待 `register_hook_ack`。
+- 若 nack/超时，会抛错并回滚本地注册状态。
+- 适用于“策略挂载失败就应立即失败”的场景。
+- `unregisterHookAndWait()` 为 hook 下线提供同样的确定性保障。
+
+```typescript
+console.table(sdk.getRegisteredHooks().map((item) => ({
+  hookId: item.hookId,
+  hookPoints: item.registration.hookPoints.join(","),
+  failPolicy: item.registration.failPolicy || "open",
+})))
+
+console.table(sdk.getHookExecutionStats().map((item) => ({
+  hookId: item.hookId,
+  invocations: item.invocationCount,
+  success: item.successCount,
+  failure: item.failureCount,
+  avgMs: Number(item.averageDurationMs.toFixed(2)),
+  lastError: item.lastError || "",
+})))
+```
+
+单点强类型注册辅助 API：
+
+```typescript
+sdk.registerHookForPoint('before_tool', {
+  matcher: { tool_names: ['run_bash_command'] },
+}, async (_ctx, payload) => {
+  // payload 在 before_tool 下是强类型
+  return { metadata: { tool: payload.tool_name } }
+})
+
+await sdk.registerHookForPointAndWait('before_tool', {
+  failPolicy: 'closed',
+}, async (_ctx, payload) => {
+  return { decision: payload.tool_name === 'delete_file' ? 'ask' : 'passthrough' }
+})
+```
+
+单点强类型 API 支持 `payloadValidation`：
+- `strict`（默认）：payload 不匹配时本次 hook 调用失败。
+- `warn`：发出 SDK `error` 事件，但继续调用 handler。
+- `off`：关闭运行时 payload 校验。
+
+Hook roundtrip 冒烟脚本：
+
+```bash
+npm --prefix packages/sdk run test:hook-roundtrip-smoke
+```
+
+该脚本会启动本地 WS mock backend，校验 13 个 hook 点的往返调用、strict 模式下 payload 不匹配失败路径、`unregisterHookAndWait` 的确定性成功/回滚路径，以及 `hookLifecycle` 事件。
+
+### Hook 动作
+
+Hook handler 返回 `null`（不干预）或 `HookResult`：
+
+```typescript
+interface HookResult {
+  skip?: boolean        // 阻断操作（如阻止工具执行）
+  value?: unknown       // 替换值（如修改后的参数或响应）
+  suspend?: boolean     // 暂停 agent，等待人工确认
+  suspend_payload?: unknown // 在 HITL 确认界面显示的数据
+  metadata?: Record<string, unknown>
+  decision?: 'deny' | 'ask' | 'passthrough' // 结构化决策
+  reason?: string      // deny/ask 的可读原因
+}
+```
+
+后端聚合优先级：`deny > ask > passthrough`。
+
+### Suspend（人机协作）
+
+Hooks 可以暂停 agent 并等待外部确认：
+
+```typescript
+sdk.registerHook({
+  hookPoints: ['before_tool'],
+  matcher: { tool_names: ['send_email'] },
+  priority: 10,
+}, async (ctx, payload) => {
+  // 人工确认后，hook 会带着 ctx.resume_value 重新触发
+  if (ctx.resume_value) {
+    return ctx.resume_value.approved ? null : { skip: true }
+  }
+  // 首次触发：挂起并显示确认界面
+  return {
+    suspend: true,
+    suspend_payload: {
+      question: `是否允许发送邮件给 ${payload.tool_args.to}？`,
+      preview: JSON.stringify(payload.tool_args).substring(0, 500),
+    },
+  }
+})
+```
+
+### 安全等级
+
+Hook 点需要最低安全等级：
+
+| 等级 | Hook 点 |
+|------|---------|
+| `standard` | on_user_prompt_submit, on_stop_failure, on_subagent_start, on_subagent_stop, on_run_start, on_run_end, on_loop, after_tool, before_compress |
+| `elevated` | before_tool, after_model, before_finalize |
+| `unrestricted` | before_model |
+
+在 SDKConfig 中设置 `requestedSecurityLevel` 以匹配所需的 hook 点。
+
+### 可靠性
+
+- **失败策略**: `"open"`（默认）-- hook 超时/错误不阻断 agent。`"closed"` -- hook 失败时阻断操作（用于安全关键的 hook）。
+- **超时**: 按 hook 点差异化（tool: 10s, model: 30s, observation: 5s）。注册时可通过 `timeout` 覆盖。
+- **熔断器**: 连续 5 次失败后自动熔断（60s 恢复期）。
+
+### Hook 可观测事件
+
+```typescript
+sdk.on('hookInvoked', (event) => {
+  console.log(event.hookPoint, event.callId, event.payload)
+})
+
+sdk.on('hookResult', (event) => {
+  console.log(event.hookPoint, event.success, event.durationMs, event.error)
+})
+
+sdk.on('hookLifecycle', (event) => {
+  console.log(
+    event.action,
+    event.hookId,
+    event.success,
+    event.deterministic,
+    event.durationMs,
+    event.error
+  )
+})
+```
+
+---
+
 ## 能力发现 (Capability Discovery)
 
 查询 Sanqian 的完整能力注册表。
@@ -1631,6 +2173,7 @@ const sdk = new SanqianSDK({
 
   // 显示
   displayName: 'My App',           // Sanqian UI 中显示的名称
+  requestedSecurityLevel: 'standard', // 可选：standard | elevated | unrestricted
 
   // 启动
   launchCommand: '/path/to/app',   // Sanqian 启动你的应用的命令
@@ -1651,6 +2194,12 @@ const sdk = new SanqianSDK({
   // 调试
   debug: false,                    // 控制台日志（默认 false）
 
+  // 注册握手（可选，默认值如下）
+  protocolVersion: '2026-03-29',   // 协议版本（YYYY-MM-DD）
+  hookCapabilities: {              // Hook 能力声明
+    streamingHook: false,          // 与后端协商（most-restrictive-wins）
+  },
+
   // 浏览器模式
   connectionInfo: undefined,       // 预配置连接信息（跳过文件发现）
 })
@@ -1745,6 +2294,8 @@ console.log(data.message.content)
 
 ## 内置工具参考
 
+下表是静态快照。运行时请以 `sdk.listTools('builtin')`（或 `/api/capabilities`）为准。
+
 ### 文件操作
 
 | 工具 | 说明 |
@@ -1834,6 +2385,12 @@ HTTP API 适合任意语言的简单对话。SDK 适合需要工具、Agent、
 
 ## Changelog
 
+### 0.3.28
+
+- Remote hooks SDK API is now available in both Node and Browser builds (`registerHook` / `unregisterHook`, hook type exports, runtime hook invoke/result handling).
+- Added `requestedSecurityLevel` handshake support and hook declaration sync in registration payloads.
+- Hardened docs to match current runtime behavior and compatibility constraints.
+
 ### 0.3.25
 
 - Centralized HTTP request pipeline: all HTTP API calls now go through a unified `httpRequest()` method that automatically injects `X-App-Token` auth headers and standardizes error handling via `SanqianSDKError`. This prevents auth header omissions and ensures consistent error types for SDK consumers.