@sepveneto/dnde-agent 0.2.0-beta.3 → 0.2.0-beta.4

package/README.md

@@ -41,9 +41,9 @@ interface AgentHostApi {
     apiMode?: 'responses' | 'chat_completions'
   }
   editor?: {
-    getCurrentEditor(): unknown | Promise<unknown>
-    getWidgets(): unknown | Promise<unknown>
-    operateEditor(operation: AgentEditorOperation): unknown | Promise<unknown>
+    getCurrentEditor: () => unknown | Promise<unknown>
+    getWidgets: () => unknown | Promise<unknown>
+    operateEditor: (operation: AgentEditorOperation) => unknown | Promise<unknown>
   }
 }
 ```
@@ -51,6 +51,33 @@ interface AgentHostApi {
 默认带三个基于编辑器 API 的工具：`get_current_editor`、`get_widgets`、
 `editor_operator`。写操作和历史不可逆操作应先取得用户确认。
 
+### 添加组件时的业务数据
+
+`items` 通常是由业务 ID 查询并组装的复杂数据，不能交给模型生成。业务工具
+应把组装结果写入当前 Agent Run 的 Context，`editor_operator` 会在 `add`
+时自动注入，并在操作成功后一次性消费：
+
+```ts
+const queryProduct = defineAgentTool({
+  name: 'query_product',
+  description: '查询商品并准备添加到编辑器。',
+  parameters: z.object({ keyword: z.string() }),
+  async execute({ keyword }, toolContext) {
+    const product = await api.product.search(keyword)
+    const items = await api.product.buildEditorItems([product.id])
+
+    // 只返回模型需要做决策的轻量信息。
+    toolContext.context.pendingItems = items
+    return { id: product.id, name: product.name }
+  },
+})
+```
+
+模型随后只调用
+`editor_operator({ action: 'add', widget: 'product', target: '页面节点 UUID' })`。
+工具参数不包含 `items`；即使模型额外传入也会被移除。每次 Agent Run 都会
+创建独立的 Context，失败时保留待添加数据以支持同一轮重试，成功后清空。
+
 ## 业务工具
 
 ```ts

package/dist/{agent-B2u2g_gS.js → agent--M87gUL-.js}

@@ -1,7 +1,7 @@
 var V = Object.defineProperty;
 var Q = (t, s, e) => s in t ? V(t, s, { enumerable: !0, configurable: !0, writable: !0, value: e }) : t[s] = e;
 var a = (t, s, e) => Q(t, typeof s != "symbol" ? s + "" : s, e);
-import { C as E, U as x, r as X, t as I, o as v, s as y, a as Z, w as A, i as q, e as ee, A as te, n as k, b as R, p as C, c as se, S as ie, d as ne, M as re, f as ae } from "./index-Cz-N1hlP.js";
+import { C as E, U as x, r as X, t as I, o as v, s as y, a as Z, w as A, i as q, e as ee, A as te, n as k, b as R, p as C, c as se, S as ie, d as ne, M as re, f as ae } from "./index-BozWbCey.js";
 function oe(t) {
   return t ? !(typeof t == "object" && t && "constructor" in t && typeof t.constructor == "function" ? t.constructor.name : "").includes("ChatCompletions") : !0;
 }

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAQ,MAAM,gBAAgB,CAAA;AAG5C,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAClD,eAAO,MAAM,qBAAqB,6BAA6B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AA4JD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;EA2BxD"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,KAAK,EAAwB,YAAY,EAAsB,MAAM,SAAS,CAAA;AACrF,OAAO,EAAE,KAAK,EAAQ,MAAM,gBAAgB,CAAA;AAO5C,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAClD,eAAO,MAAM,qBAAqB,6BAA6B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAsLD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;EA8BxD"}

package/dist/editorContext.d.ts

@@ -0,0 +1,26 @@
+import type { AgentEditorOperation, EditorAgentContext } from './types';
+/**
+ * Create isolated editor/business state for one Agent Run.
+ *
+ * Host context is copied in as read-only starting data. `pendingItems` is
+ * always reset so data prepared by a previous turn cannot leak into this one.
+ */
+export declare function createEditorAgentContext(initial?: Record<string, unknown>): EditorAgentContext;
+export interface PreparedEditorOperation {
+    operation: AgentEditorOperation;
+    /** Items reserved for this add operation; cleared only after success. */
+    pendingItems?: unknown[];
+    error?: string;
+}
+/**
+ * Remove any model-produced items and, for add operations, inject the data
+ * prepared by a business tool for this run.
+ */
+export declare function prepareEditorOperation(input: unknown, context: EditorAgentContext): PreparedEditorOperation;
+export declare function editorOperationSucceeded(result: unknown): boolean;
+/**
+ * Consume pending items only after the editor confirms success. A failed
+ * operation keeps them available for a corrected retry in the same Run.
+ */
+export declare function completeEditorOperation(context: EditorAgentContext, prepared: PreparedEditorOperation, result: unknown): void;
+//# sourceMappingURL=editorContext.d.ts.map

package/dist/editorContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorContext.d.ts","sourceRoot":"","sources":["../src/editorContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,SAAS,CAAA;AAEhB;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,kBAAkB,CAKpB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,oBAAoB,CAAA;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,kBAAkB,GAC1B,uBAAuB,CA6BzB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CASjE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,uBAAuB,EACjC,MAAM,EAAE,OAAO,GACd,IAAI,CAGN"}