page-agent-sdk 2.11.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "type": "module",
   "description": "框架无关的页面内 Agent JS SDK —— 以对话框形态挂载到任意网页,通过自定义 tool 读写宿主预注册的数据槽(经 schema 校验 + jsonPath 增量 patch + 快照回退;GET 抓文档),具备 planning/skills/虚拟工作区/context 管理能力。Vue 打包进库,使用者无需安装 Vue。",
   "main": "./dist/page-agent-sdk.umd.cjs",

package/skills/page-agent-sdk-integrate/references/advanced.md

@@ -276,3 +276,31 @@ createChatSdk({
   checkpoint: true,                             // rollback
 }).mount()
 ```
+
+## 6. Runtime dynamic reconfiguration (tools / llm / memory / subagents)
+
+Beyond `setData` / `setSkills`, you can dynamically reconfigure **tools / LLM / memory / pre-declared subagents** at runtime — zero-breakage (not calling = current behavior), no agent rebuild (preserves conversation history & middleware state). All setters trigger `infoTick++` → DebugDrawer refresh; `inspect()` reflects the latest tools/model/memory/subagent.subagents.
+
+```ts
+// 1. Tools: swap/append/remove user tools at runtime (built-ins untouched; internal rebind)
+sdk.setTools([toolA, toolB])            // replace user tool set (built-ins stay)
+sdk.addTool(toolC)                      // append (dedup by name)
+sdk.removeTool('toolA')                 // remove by name → boolean
+
+// 2. LLM: switch model at runtime (quota-exhausted→cheaper / complex task→stronger / switch provider)
+sdk.setLlm({ apiKey, baseUrl, model: 'gpt-4o' })   // LLMConfig form (constructs ChatOpenAI)
+sdk.setLlm(otherChatModel)                          // or pass a BaseChatModel instance
+// rebinds tools + re-resolves model caps (contextWindow/maxOutputTokens); summaryLlm unaffected
+
+// 3. Memory: update persistent directive at runtime (next augmentPrompt injects latest)
+sdk.setMemory('User is VIP; prefer concise answers; use incremental patch when editing.')
+sdk.setMemory('')   // clear (empty string skips injection)
+
+// 4. Subagents: runtime add/remove pre-declared subagents (requires subagents:[] at creation)
+//    Pass subagents: [] (empty array) at creation to enable the controller for dynamic add later.
+sdk.addSubagent({ id: 'translator', description: '中英互译子 agent', systemPrompt: '你是翻译助手。' })
+sdk.removeSubagent('translator')        // → boolean
+sdk.setSubagents([{ id: 'a', description: 'A' }, { id: 'b', description: 'B' }])  // replace all
+```
+
+> **Note**: `setSystemPrompt` / `setMiddleware` (runtime middleware-array swap) are not yet implemented — they touch the harness core and are deferred. Use `setData` / `setSkills` / `augmentSystem` hook to cover most dynamic system-prompt scenarios. See `doc/roadmap.md` #5.

package/skills/page-agent-sdk-integrate/references/api.md

@@ -19,6 +19,14 @@
 | `setSkills(skills)` | `(skills: SkillSpec[]) => void` | Runtime swap the entire skill list (same-name skill overwrites). Takes effect next round: the skill index section of the system prompt re-renders with the new skills; clears the skill full-text cache & in-round loaded set, so the next `load_skill` re-fetches the latest full text (incl. vfs doc). Requires skills enabled (default on). |
 | `invalidateSkillCache(name?)` | `(name?: string) => void` | Invalidate the skill full-text cache (proactive invalidation when a dynamic skill's content changes). Omit `name` to clear all; pass `name` to clear one. The next `load_skill` re-runs `getContent`/`readSkillDoc`. Requires skills enabled (default on). |
 | `usage` | `TokenUsage` | Cumulative token usage `{prompt_tokens, completion_tokens, total_tokens}` (accumulated per LLM call). |
+| `setTools(tools)` | `(tools: StructuredToolInterface[]) => void` | Runtime swap user tools (built-ins untouched; internal `rebindTools` re-binds to LLM; next round uses new set). Zero-breakage: not calling = current behavior. Supports per-permission/business-stage/A-B-test dynamic tool groups without rebuilding agent. |
+| `addTool(tool)` | `(tool: StructuredToolInterface) => void` | Append user tool at runtime (dedup by name; built-ins untouched). |
+| `removeTool(name)` | `(name: string) => boolean` | Remove user tool at runtime (built-ins untouched). Returns whether removed. |
+| `setLlm(llm)` | `(llm: BaseChatModel \| LLMConfig) => void` | Switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig` (constructs `ChatOpenAI` internally). Rebinds tools + re-resolves model caps (`contextWindow`/`maxOutputTokens`). `summaryLlm` unaffected. If new model lacks `bindTools`, tool-calling degrades (agent stays up). |
+| `setMemory(text)` | `(text: string) => void` | Update persistent memory directive at runtime (next `augmentPrompt` injects latest; `setMemory('')` clears). |
+| `setSubagents(configs)` | `(configs: SubagentConfig[]) => void` | Runtime swap pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation (else controller is null, setter warns, no throw). |
+| `addSubagent(config)` | `(config: SubagentConfig) => void` | Append pre-declared subagent at runtime (duplicate id warns & skips). Requires `subagents:[]` at creation. |
+| `removeSubagent(id)` | `(id: string) => boolean` | Remove pre-declared subagent at runtime (by id). Returns whether removed. Requires `subagents:[]` at creation. |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
 | `addSkill(skill)` | `(skill: { name, description, prompt \| getContent \| doc }) => void` | Add a user-created skill at runtime. Auto-merges into the skill list, persists via **independent SkillStore** (default indexedDB, separate from `storage` option), takes effect next round. Same-name overwrites. Requires `capabilities.skills` (default on) + `skillStorage` not `false` for persistence. |
@@ -164,6 +172,12 @@ createChatSdk({
 - **Notifying the outside world of changes**: subscribe `data_change` via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable) — fires after `write`/`set`/`edit`/`delete`/`restore`, with `operation`/`value`. For Vue + reactive bind, template/watch auto-react (no manual notify needed); `onEvent` can coexist for audit/analytics.
 - **Runtime swap**: `sdk.setData({ schema, bind, description? })` replaces the whole config; tools pick up immediately (no rebuild). Snapshots & lock hash reset.
 - **Runtime skill swap**: `sdk.setSkills(skills)` replaces the entire skill list (same-name overwrites); the skill index section of the system prompt re-renders next round, and the skill full-text cache is cleared so the next `load_skill` re-fetches the latest content (incl. vfs doc). Use `sdk.invalidateSkillCache(name?)` to proactively invalidate the cache when a dynamic skill's content changes (without swapping the whole list).
+- **Runtime dynamic reconfiguration (zero-breakage; not calling = current behavior)**: beyond data/skills, you can also dynamically reconfigure tools / LLM / memory / subagents at runtime without rebuilding the agent:
+  - `sdk.setTools(tools)` / `addTool(tool)` / `removeTool(name)` — swap/append/remove user tools (built-ins untouched; internal `rebindTools` re-binds to LLM; next round uses new set). Use cases: per-permission tool groups, business-stage gating, A/B experiments.
+  - `sdk.setLlm(llm)` — switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig`. Rebinds tools + re-resolves model caps. `summaryLlm` unaffected.
+  - `sdk.setMemory(text)` — update the persistent memory directive at runtime (next `augmentPrompt` injects latest).
+  - `sdk.setSubagents(configs)` / `addSubagent(config)` / `removeSubagent(id)` — swap/append/remove pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation.
+  - All setters trigger `infoTick++` → DebugDrawer refreshes; `inspect()` reflects the latest tools/model/memory/subagent.subagents.
 
 ## Exported building blocks (for custom UIs)
 

package/skills/page-agent-sdk-integrate/references/options.md

@@ -9,6 +9,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | `llm` | `LLMConfig \| BaseChatModel` | — (required) | The model. `LLMConfig = { apiKey, baseUrl, model, temperature?, maxTokens? }` (OpenAI-compatible; DeepSeek default). Or pass any LangChain `BaseChatModel` (e.g. `ChatAnthropic`, install its peerDep). |
 | `systemPrompt` | `string` | built-in default (JSON-operation assistant + reliable write rules) | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). If omitted, a built-in default is used (JSON-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it. |
 | `appendReliableWriteRules` | `boolean` | `true` | When `true` (default) and a custom `systemPrompt` is set, auto-append `systemPromptHelpers.reliableWriteRules` to it with a `---` separator (clearly distinguishes user content from SDK-appended write rules; avoids forgetting the write rules). Set `false` to disable. No effect when `systemPrompt` is omitted (default prompt already includes them). |
+| `augmentSystem` | `(ctx:{state,data?}) => string \| undefined` | — | Dynamic system-prompt injection hook. Called each turn; return a string to inject as a segment, or `undefined` to skip. Callback errors degrade to skip (no crash). `ctx.data` is taken from `liveData()` each turn (auto-syncs after `setData`), so you can compute dynamic component descriptions / partial schema hints from current runtime state. Segment is placed after built-in segments (base/dataHint/usageHints/.../subagents) and before user `middleware`. Not set = current behavior (no segment). See `doc/system-prompt.md` §B6. |
 | `id` | `string` | random + warn | Stable agent id for multi-agent isolation & persistence. **Must pass a stable value** if you use `storage` or run multiple agents on one page. |
 
 ## UI & mounting
@@ -98,7 +99,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
 | `subagent` | `object` | enabled | `{ enabled?, allowedTools?, systemPrompt?, temperature?, maxTokens?, skills?, llm?, maxDepth?, maxParallel? }`. `maxDepth` (1) physically cuts recursion. Subagents get a read-only tool subset (no spawn). |
-| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. |
+| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. Pass `[]` (empty array) to enable the `SubagentsController` for runtime `addSubagent`/`removeSubagent`/`setSubagents` (initial no subagents, add dynamically later). |
 
 ## Verify (self-check before return)
 

package/types/index.d.ts

@@ -110,6 +110,8 @@ export interface SubagentInfo {
   maxDepth: number;
   maxParallel: number;
   allowedTools: string[];
+  /** 预声明子 agent 列表(动态:反映 setSubagents/addSubagent/removeSubagent 后的最新) */
+  subagents?: { id: string; description: string }[];
 }
 /** 预声明子 agent 配置(同主配置子集 + id/description;缺省继承主 agent) */
 export interface SubagentConfig {
@@ -369,6 +371,16 @@ export interface SessionOptions {
   title?: string;
 }
 
+/**
+ * augmentSystem 钩子上下文:集成方回调据此按运行时状态动态注入 system prompt 段。
+ * - `state`:harness 当前状态(messages/todos/files/skills/memory…);不含 data(data 是 createChatSdk 层概念)
+ * - `data`:当前主数据配置(每轮从 liveData() 取最新,setData 后自动同步;含 schema/bind/description)
+ */
+export interface SystemAugmentContext {
+  state: any;
+  data?: DataConfig;
+}
+
 export interface ChatSdkOptions {
   container?: string | HTMLElement;
   /** UI:'default'(内置 ChatDialog)/ false(headless 不渲染,自建 UI) */
@@ -382,9 +394,17 @@ export interface ChatSdkOptions {
   session?: SessionOptions;
   /** 共享上下文:默认 false;true 时同 id 复用同一核心(messages/agent/工作区) */
   shareContext?: boolean;
+  /** 系统提示词(base + 可操作数据段,数据段随 data 动态;不含 todos/skills/memory/augmentSystem 等运行态 augmentPrompt 段) */
   systemPrompt?: string;
   /** 自定义 systemPrompt 时是否自动追加 reliableWriteRules(默认 true,用 '---' 分隔线区分;设 false 关闭;不传 systemPrompt 用默认 prompt 时已内置,此项无效) */
   appendReliableWriteRules?: boolean;
+  /**
+   * 动态 system prompt 注入钩子:每轮 buildSystemPrompt 时调用,集成方按运行时状态(state/data)返回字符串 → 作为 system prompt 一段注入;返回 undefined → 跳过。
+   * - ctx.data 每轮从 liveData() 取最新(setData 后自动同步),可据此动态算组件说明 / 部分 schema 描述
+   * - 回调异常降级为跳过该段 + debug 日志(不崩 agent)
+   * - 段排在内置段之后、用户 middleware 之前;不配 = 完全现状行为
+   */
+  augmentSystem?: (ctx: SystemAugmentContext) => string | undefined;
   tools?: any[];
   skills?: SkillSpec[];
   /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
@@ -525,6 +545,22 @@ export interface ChatSdk {
   pendingConflict: Ref<PendingConflict | null>;
   /** 冲突解决:用户点「保留外部」(keep_external)/「强制覆盖」(overwrite)/「回退」(restore) → 收口挂起的 conflict,被挂起的工具调用继续 */
   resolveConflict(action: ConflictResolution['action']): void;
+  /** 运行时替换用户工具集(内置工具不动);立即 rebind + infoTick 刷新 */
+  setTools(tools: any[]): void;
+  /** 运行时追加用户工具(去重 by name);立即生效 */
+  addTool(tool: any): void;
+  /** 运行时移除用户工具(by name;内置不动);返回是否移除成功 */
+  removeTool(name: string): boolean;
+  /** 运行时切换 LLM(BaseChatModel 或 LLMConfig);rebind + 重解析能力 + infoTick */
+  setLlm(llm: ChatModelLike | LLMConfig): void;
+  /** 运行时更新 memory 文本;立即生效 + infoTick */
+  setMemory(text: string): void;
+  /** 运行时替换预声明子 agent 列表(重新生成委派工具 + rebind);需创建时配 subagents:[] */
+  setSubagents(configs: SubagentConfig[]): void;
+  /** 运行时追加预声明子 agent(id 重复 warn 跳过);需创建时配 subagents:[] */
+  addSubagent(config: SubagentConfig): void;
+  /** 运行时移除预声明子 agent(by id);返回是否移除成功;需创建时配 subagents:[] */
+  removeSubagent(id: string): boolean;
 }
 
 /** 乐观锁冲突挂起(dataOps 写入时 expectedHash 不匹配,挂起等用户决定) */
@@ -683,6 +719,12 @@ export interface StateUpdate { [k: string]: any }
 
 // 子 agent
 export declare function createSubagentsMiddleware(opts: any): any;
+export interface SubagentsController {
+  set(configs: SubagentConfig[]): void;
+  add(config: SubagentConfig): void;
+  remove(id: string): boolean;
+  get(): SubagentConfig[];
+}
 export interface SubagentOptions { [k: string]: any }
 export interface SubagentLlmConfig { [k: string]: any }