@gencode/plugin-sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @gencode/plugin-sdk
 
+## 0.7.1
+
+### Patch Changes
+
+- bc161b3: Expose the current user data root on plugin hook context as `ctx.dataDir`. Plugin hooks can now distinguish the persistent AIMax data directory from the effective working directory exposed as `ctx.workspaceDir`, which may point to `--project-dir` when a run is scoped to a specific repository.
+- d77a70b: 插件现在可以通过 `api.hitl.pause()` 发起持久化人工确认，并通过 `api.hitl.isPause()` 识别暂停信号。插件只需使用 `@gencode/plugin-sdk` 的类型，不再需要运行时引入 `@gencode/agents`；请求 ID、当前会话 ID 和创建时间由 AIMax 自动补齐，现有暂停、恢复与外部事件行为保持不变。
+- Updated dependencies [bc161b3]
+- Updated dependencies [d77a70b]
+  - @gencode/agents@0.18.1
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -108,6 +108,47 @@ WebSocket / callback 中的事件载荷核心字段：
   - `progress_demo.fetch.completed`
   - `progress_demo.report.generated`
 
+## `api.hitl`
+
+自定义 tool 或 hook 需要主动发起持久化 HITL 暂停时，使用宿主注入的 `api.hitl.pause()`。插件不需要、也不应运行时引入 `@gencode/agents`：
+
+```ts
+import type { PluginApi } from "@gencode/plugin-sdk";
+
+export default function register(api: PluginApi) {
+  api.registerTool({
+    name: "approve_action",
+    description: "Request approval for an action",
+    parameters: { type: "object", properties: {} },
+    async execute(toolCallId, params) {
+      api.hitl.pause({
+        request: {
+          kind: "approval",
+          title: "操作审批",
+          prompt: "是否继续？",
+          input: {
+            mode: "choice",
+            choices: [
+              { id: "approve", label: "允许" },
+              { id: "deny", label: "拒绝" },
+            ],
+          },
+          policy: { resumable: true, defaultOnTimeout: "deny" },
+        },
+        checkpoint: {
+          turnId: toolCallId,
+          phase: "before_tool",
+          resumeStrategy: "reenter_from_checkpoint",
+        },
+        toolContext: { toolCallId, toolName: "approve_action", toolArgs: params },
+      });
+    },
+  });
+}
+```
+
+宿主负责生成 `requestId`、绑定当前 `sessionId` 并填写 `createdAt`。需要在异常包装逻辑中识别控制信号时，使用 `api.hitl.isPause(error)`。
+
 ## `registerUiTool`
 
 插件可以通过 `api.registerUiTool()` 注册 UI 工具，让 LLM 在需要时暂停 agent 并通过前端表单收集结构化用户输入。

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * @gencode/plugin-sdk
  * Thin re-export layer for plugin authors.
  */
-export type { UiToolInputSchema, AgentCustomProgressEvent, PluginApi, PluginRegistry, PluginRecord, PluginDiagnostic, PluginKind, PluginOrigin, PluginManifest, PluginManifestLoadResult, PluginConfigUiHint, PluginProgressEmitter, PluginCustomProgressInput, PluginUiToolDescriptor, PluginUiToolOptions, } from "@gencode/agents";
+export type { UiToolInputSchema, AgentCustomProgressEvent, PluginApi, PluginRegistry, PluginRecord, PluginDiagnostic, PluginKind, PluginOrigin, PluginManifest, PluginManifestLoadResult, PluginConfigUiHint, PluginProgressEmitter, PluginCustomProgressInput, PluginUiToolDescriptor, PluginUiToolOptions, PluginHitlApi, PluginHitlPauseInput, PluginHitlPauseSignal, PluginHitlRequest, } from "@gencode/agents";
 export type { MemoryProvider, MemoryProviderContext, MemoryProviderFactory, MemoryProviderRegistration, MemorySearchOptions, MemoryChangeSource, MemoryChangedEvent, MemoryChangedHandler, } from "@gencode/agents";
 export type { EmbeddingProvider, EmbeddingProviderContext, EmbeddingProviderFactory, EmbeddingProviderRegistration, } from "@gencode/agents";
 export type { PluginHookName, PluginHookHandlerMap, PluginHookAgentContext, PluginHookBeforeModelResolveEvent, PluginHookBeforeModelResolveResult, PluginHookBeforePromptBuildEvent, PluginHookBeforePromptBuildResult, PluginHookLlmInputEvent, PluginHookLlmOutputEvent, PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult, PluginHookAfterToolCallEvent, PluginHookBeforeAgentStartEvent, PluginHookBeforeAgentStartResult, PluginHookToolResultEvent, PluginHookToolResultResult, PluginHookTurnStartEvent, PluginHookTurnEndEvent, PluginHookAgentStartEvent, ReadonlyTranscriptSessionAdapter, PluginHookAgentEndEvent, PluginHookBeforeCompactionEvent, PluginHookAfterCompactionEvent, PluginHookSessionStartEvent, PluginHookSessionEndEvent, PluginHookSessionResetEvent, PluginHookMemoryChangedEvent, PluginHookInputEvent, PluginHookInputResult, PluginHookResourcesDiscoverEvent, PluginHookResourcesDiscoverResult, PluginHookContextEvent, PluginHookContextResult, PluginHookBeforeProviderRequestEvent, PluginHookBeforeProviderRequestResult, PluginHookRegistration, PluginHookAfterPromptBuildEvent, } from "@gencode/agents";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,uBAAuB,EACvB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,oBAAoB,EACpB,qBAAqB,EACrB,gCAAgC,EAChC,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,EACvB,oCAAoC,EACpC,qCAAqC,EACrC,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,uBAAuB,EACvB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,oBAAoB,EACpB,qBAAqB,EACrB,gCAAgC,EAChC,iCAAiC,EACjC,sBAAsB,EACtB,uBAAuB,EACvB,oCAAoC,EACpC,qCAAqC,EACrC,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gencode/plugin-sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,8 +18,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@gencode/shared": "0.6.0",
-    "@gencode/agents": "0.18.0"
+    "@gencode/agents": "0.18.1",
+    "@gencode/shared": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"