qlogicagent 2.13.3 → 2.13.5

package/dist/orchestration/workflow-chat-builder.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workflow Chat Builder (M4) — 自动化页"意图先行"的对话搭图/改图(D18/D17)。
+ *
+ * 与 solo-spec-builder.runSpecChatRound 同构:进程内 runForkedAgent + 受限工具,纯推理产出,
+ * 不直接落库。区别:产出的是 **工作流提案**——新建给完整 WorkflowDef,改已有给 WorkflowPatch[]。
+ * 应用由调用方(前端经既有 workflow.create/patch RPC,触发 WS 回流画布)完成,故本轮无副作用、
+ * 也无需访问引擎控制器。
+ */
+import type { ForkedAgentRunnerFactory } from "../runtime/ports/agent-execution-contracts.js";
+import type { LLMTransport } from "../runtime/ports/index.js";
+import type { ToolDefinition, AgentLogger } from "../agent/types.js";
+import { type CapabilityEntry } from "./workflow/capability-catalog.js";
+/** agent 通过此工具产出工作流提案:新建给 def,改已有给 patch。 */
+export declare const PROPOSE_WORKFLOW_TOOL_NAME = "propose_workflow";
+export declare const PROPOSE_WORKFLOW_TOOL_DEF: ToolDefinition;
+/** 单轮入参。history 含到本轮为止的完整对话(末条为用户最新消息)。currentWorkflow 为已有图的渲染文本(改图上下文)。
+ *  v1 不带 ask_user(不反问;直接用默认搭,用户再说一句改),故澄清往返的网关路由也无需接。 */
+export interface WorkflowChatDeps {
+    history: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+    currentWorkflow?: string;
+    /** D19 框选局部修改:用户框选的节点 id;非空时指示 agent 只产出 scoped patch(引擎按同 scope 强制)。 */
+    scope?: string[];
+    /**
+     * 真实能力目录(spec D24/IT-3):agent/tool/skill/mcp/memory(+网关注入的 channel)。
+     * 注入后:① 系统提示带紧凑清单 ② agent 可用 list_capabilities 查长尾 ③ propose_workflow
+     * 校验回环拒绝引用目录外能力(反幻觉)。缺省(无目录)时退回静态 kind 说明、不做 ref 校验。
+     */
+    catalog?: CapabilityEntry[];
+    transport: LLMTransport;
+    apiKey: string;
+    model: string;
+    createAgentRunner: ForkedAgentRunnerFactory;
+    log: AgentLogger;
+    parentSignal?: AbortSignal;
+}
+export interface WorkflowChatResult {
+    reply: string;
+    def?: Record<string, unknown>;
+    patch?: unknown[];
+    trigger?: Record<string, unknown>;
+    /**
+     * Fail-loud(§3/EX-A):本轮 agent 调过 propose_workflow 但**没有任何一次通过校验**时带上
+     * (attempts=被拒次数,errors=最后一次的校验错误)。reply 此时只是 agent 的口头方案,
+     * **不是**已落图的提案 —— 前端必须把失败 + 重试出路显式给用户,不许当正常回复展示。
+     */
+    rejected?: {
+        attempts: number;
+        errors: string[];
+    };
+}
+/** agent 按需检索能力长尾(系统提示只放每类前 N 条)。 */
+export declare const LIST_CAPABILITIES_TOOL_NAME = "list_capabilities";
+/** 跑一轮对话式搭图/改图,返回自然语言 reply + 工作流提案(def 新建 / patch 改已有)。失败抛,由调用方降级。 */
+export declare function runWorkflowChatRound(deps: WorkflowChatDeps): Promise<WorkflowChatResult>;

package/dist/orchestration/workflow-chat-builder.js

@@ -0,0 +1,202 @@
+/**
+ * Workflow Chat Builder (M4) — 自动化页"意图先行"的对话搭图/改图(D18/D17)。
+ *
+ * 与 solo-spec-builder.runSpecChatRound 同构:进程内 runForkedAgent + 受限工具,纯推理产出,
+ * 不直接落库。区别:产出的是 **工作流提案**——新建给完整 WorkflowDef,改已有给 WorkflowPatch[]。
+ * 应用由调用方(前端经既有 workflow.create/patch RPC,触发 WS 回流画布)完成,故本轮无副作用、
+ * 也无需访问引擎控制器。
+ */
+import { runForkedAgent } from "../runtime/execution/forked-agent.js";
+import { validateWorkflowDef } from "./workflow/workflow-patch.js";
+import { renderCatalogForPrompt, validateCapabilityRefs } from "./workflow/capability-catalog.js";
+/** LLM 常把 nodeId 误写成 id;对引用节点的 op 归一化,避免 patch 在 apply 时因字段名被拒。 */
+function normalizePatchOp(op) {
+    if (op && typeof op === "object") {
+        const o = op;
+        if (o.id != null && o.nodeId == null && (o.op === "update_params" || o.op === "rename_node" || o.op === "remove_node")) {
+            return { ...o, nodeId: o.id };
+        }
+    }
+    return op;
+}
+/** agent 通过此工具产出工作流提案:新建给 def,改已有给 patch。 */
+export const PROPOSE_WORKFLOW_TOOL_NAME = "propose_workflow";
+export const PROPOSE_WORKFLOW_TOOL_DEF = {
+    type: "function",
+    function: {
+        name: PROPOSE_WORKFLOW_TOOL_NAME,
+        description: "产出或更新自动化工作流。新建工作流给完整 def;修改已有工作流给 patch(WorkflowPatch op 数组,引用现有节点 id)。",
+        parameters: {
+            type: "object",
+            properties: {
+                def: {
+                    type: "object",
+                    description: "完整 WorkflowDef:{ nodes:[{id,kind,name?,params?,outPorts?}], edges:[{from,to,fromPort?,toPort?}], trigger? } —— 新建时给",
+                },
+                patch: {
+                    type: "array",
+                    items: { type: "object" },
+                    description: "WorkflowPatch op 数组(add_node/remove_node/update_params/rename_node/add_edge/remove_edge/set_trigger/set_meta)—— 改已有时给。引用节点的 op 用字段名 **nodeId**(不是 id):如 {op:'update_params',nodeId:'x',params:{...}}、{op:'rename_node',nodeId:'x',name:'...'}。",
+                },
+                trigger: {
+                    type: "object",
+                    description: "TriggerDef:{type:'manual'} | {type:'schedule',cron} | {type:'im-message',channel,match?} | {type:'webhook',path} —— 新建时给(决定如何触发;不确定就 manual)",
+                },
+                note: { type: "string", description: "给用户的一句话说明本次产出/改动" },
+            },
+        },
+    },
+};
+const WORKFLOW_CHAT_SYSTEM_PROMPT = `你是自动化工作流的搭建助手(中立、对话式)。把用户用大白话描述的"想自动化的事",转成一张可执行的工作流图。
+
+节点种类(kind):
+- trigger:入口。在 def.trigger 定触发:{type:"manual"} | {type:"schedule",cron:"0 9 * * *"} | {type:"im-message",channel,match?} | {type:"webhook",path}
+- agent:跑一个 AI agent。params {prompt, agentId?}(不填 agentId 即用小智本体执行,推荐)
+- tool:调 qlogicagent 工具。params {tool, args?}
+- http:HTTP 请求。params {method?,url,headers?,body?}
+- mcp:MCP 工具。params {server,tool,args?}
+- channel:发到 IM(飞书/微信…)。params {channel,target?,payload}
+- if:条件分支。params {condition},出端口 true/false
+- set/merge/passthrough:数据处理
+边 edge:{from,to,fromPort?(默认 "default";if 用 "true"/"false"),toPort?}。params 可用 {{ $node("id").output.default[0].json.x }} 引用上游输出。
+表达式是受限语言:只有路径取值($json/$vars/$trigger/$input/$node("id").output…)和 len/upper/lower/default/jsonpath/date 函数;**没有**运算符(+ - || ?:)、管道(|)、JS 方法(.toLowerCase() 等)——需要计算/改写文本时用 agent 节点做。
+
+示例(「每天9点抓新闻→AI总结→发飞书」,照此结构产出):
+{
+  "nodes": [
+    {"id":"t","kind":"trigger","name":"每天 9:00"},
+    {"id":"fetch","kind":"http","name":"抓新闻","params":{"method":"GET","url":"https://newsapi.org/..."}},
+    {"id":"sum","kind":"agent","name":"AI 总结","params":{"prompt":"把这些新闻总结成3条要点:{{ $node(\\"fetch\\").output.default[0].json }}"}},
+    {"id":"send","kind":"channel","name":"发飞书","params":{"channel":"feishu","payload":"{{ $node(\\"sum\\").output.default[0].json.text }}"}}
+  ],
+  "edges": [{"from":"t","to":"fetch"},{"from":"fetch","to":"sum"},{"from":"sum","to":"send"}],
+  "trigger": {"type":"schedule","cron":"0 9 * * *"}
+}
+要点:trigger 是唯一入口;每个后续节点都有来自上游的入边、串成一条链;节点 id 简短稳定;def.trigger 决定触发方式。
+
+流程(每轮):
+1. **不要反问澄清**;信息不全就用合理默认直接搭(用户看到图后会再说一句改)。
+2. 调用 ${PROPOSE_WORKFLOW_TOOL_NAME}:新建工作流给完整 def(含 trigger + 各节点稳定 id);修改已有工作流给 patch(引用上下文里给出的现有节点 id)。
+3. 用一句简短自然语言回复用户(或写在 note 里),说明本次产出/改动 + 用了哪些默认(便于用户决定要不要改)。
+约束:只产出工作流提案,不直接执行、不改任何文件。`;
+/** agent 按需检索能力长尾(系统提示只放每类前 N 条)。 */
+export const LIST_CAPABILITIES_TOOL_NAME = "list_capabilities";
+const LIST_CAPABILITIES_TOOL_DEF = {
+    type: "function",
+    function: {
+        name: LIST_CAPABILITIES_TOOL_NAME,
+        description: "列出当前可用的真实能力(agent/tool/skill/mcp/channel/memory)。搭图前不确定某能力是否存在时先查;引用目录外能力会被校验拒绝。",
+        parameters: {
+            type: "object",
+            properties: {
+                category: { type: "string", enum: ["agent", "tool", "skill", "mcp", "channel", "memory"], description: "只列某一类;缺省列全部" },
+                query: { type: "string", description: "按名称/描述过滤的关键词" },
+            },
+        },
+    },
+};
+/** 跑一轮对话式搭图/改图,返回自然语言 reply + 工作流提案(def 新建 / patch 改已有)。失败抛,由调用方降级。 */
+export async function runWorkflowChatRound(deps) {
+    let lastDef;
+    let lastPatch;
+    let lastTrigger;
+    let lastNote;
+    // Fail-loud bookkeeping: every rejected propose (validation/parse) is counted; if the loop
+    // ends with rejections and NO accepted proposal, the result carries `rejected` so the UI
+    // surfaces a real failure + retry instead of presenting the agent's apology as success.
+    let rejectedAttempts = 0;
+    let lastRejectErrors = [];
+    const catalog = deps.catalog;
+    const toolInvoker = {
+        invoke: async (_turnId, name, args) => {
+            if (name === LIST_CAPABILITIES_TOOL_NAME && catalog) {
+                try {
+                    const a = args ? JSON.parse(args) : {};
+                    const q = a.query?.toLowerCase();
+                    const hits = catalog
+                        .filter((e) => (!a.category || e.category === a.category)
+                        && (!q || e.id.toLowerCase().includes(q) || e.label.toLowerCase().includes(q) || (e.description ?? "").toLowerCase().includes(q)))
+                        .slice(0, 60)
+                        .map((e) => ({ category: e.category, id: e.id, label: e.label, description: e.description }));
+                    return { result: JSON.stringify(hits) };
+                }
+                catch {
+                    return { result: "Invalid list_capabilities arguments.", error: "parse_error" };
+                }
+            }
+            if (name === PROPOSE_WORKFLOW_TOOL_NAME) {
+                try {
+                    const a = JSON.parse(args);
+                    if (a.def && typeof a.def === "object") {
+                        // NL→graph quality: validate the proposed def in-loop (same check workflow.create runs),
+                        // so the agent fixes errors within its remaining turns instead of producing a def that
+                        // only fails later at apply-time.
+                        const errs = validateWorkflowDef(a.def);
+                        // Anti-hallucination (D24): every agent/tool/skill/mcp/channel ref must exist in the
+                        // real catalog — reject in-loop so the agent re-wires instead of shipping a dead graph.
+                        if (catalog)
+                            errs.push(...validateCapabilityRefs(a.def, catalog));
+                        if (errs.length > 0) {
+                            rejectedAttempts += 1;
+                            lastRejectErrors = errs;
+                            return {
+                                result: `工作流校验未通过:\n- ${errs.join("\n- ")}\n请修正后重新调用 ${PROPOSE_WORKFLOW_TOOL_NAME}(规则:每个非 trigger 节点要有来自上游的入边;只一个 trigger 入口;节点 id 稳定且被 edges.from/to 引用;边端口 fromPort 默认 "default",if 用 "true"/"false";能力引用必须来自 ${LIST_CAPABILITIES_TOOL_NAME} 可查到的真实目录;表达式只支持 $json/$vars/$trigger/$input/$node("节点id").output.default[0].json.字段 的路径取值与 len/upper/lower/default/jsonpath/date 函数 —— 没有运算符、管道、方法调用)。`,
+                                error: "validation_failed",
+                            };
+                        }
+                        lastDef = a.def;
+                    }
+                    if (Array.isArray(a.patch))
+                        lastPatch = a.patch.map(normalizePatchOp);
+                    if (a.trigger && typeof a.trigger === "object")
+                        lastTrigger = a.trigger;
+                    if (typeof a.note === "string")
+                        lastNote = a.note;
+                    return { result: "工作流提案已记录(校验通过)" };
+                }
+                catch {
+                    rejectedAttempts += 1;
+                    lastRejectErrors = ["propose_workflow 参数不是合法 JSON(模型输出被截断或格式损坏)"];
+                    return { result: "Invalid propose_workflow arguments.", error: "parse_error" };
+                }
+            }
+            return { result: `Tool ${name} is not available in the workflow chat phase.` };
+        },
+    };
+    let systemPrompt = deps.currentWorkflow
+        ? `${WORKFLOW_CHAT_SYSTEM_PROMPT}\n\n当前工作流(改图时引用其节点 id):\n${deps.currentWorkflow}`
+        : WORKFLOW_CHAT_SYSTEM_PROMPT;
+    if (catalog && catalog.length > 0) {
+        systemPrompt += `\n\n【可用的真实能力清单(D24)】节点引用的 agentId/tool/skill/server.tool/channel **必须**出自这份目录(引用目录外能力会被校验拒绝;不确定先用 ${LIST_CAPABILITIES_TOOL_NAME} 查):\n${renderCatalogForPrompt(catalog)}`;
+    }
+    if (deps.scope?.length) {
+        systemPrompt += `\n\n【框选局部修改 D19】用户只框选了这些节点:${deps.scope.join(", ")}。本轮做外科手术式局部改:**产出 patch(不要给完整 def)**,只允许 update_params/rename_node 选区内节点、add_node 并把它连到选区边界、增删"至少一端在选区内"的边;**禁止改动/删除选区外的节点,禁止动两端都在选区外的边**(越界会被引擎整笔拒绝)。`;
+    }
+    const promptMessages = deps.history.map((h) => ({ role: h.role, content: h.content }));
+    const res = await runForkedAgent({
+        promptMessages,
+        systemPrompt,
+        tools: catalog ? [PROPOSE_WORKFLOW_TOOL_DEF, LIST_CAPABILITIES_TOOL_DEF] : [PROPOSE_WORKFLOW_TOOL_DEF],
+        transport: deps.transport,
+        toolInvoker,
+        createAgentRunner: deps.createAgentRunner,
+        apiKey: deps.apiKey,
+        model: deps.model,
+        log: deps.log,
+        forkLabel: "workflow-chat",
+        // 一次被拒的 propose 要花 2 轮才能修复(重试+确认);6 轮在"目录查询+两次被拒"下就见底
+        // (真机 2026-06-12 失败实例:预算耗尽后 agent 以道歉文本收场)。8 轮容 3 个修复循环。
+        maxTurns: 8,
+        parentSignal: deps.parentSignal,
+    });
+    const text = res.events
+        .filter((e) => e.type === "end" && "content" in e)
+        .map((e) => e.content ?? "").join("")
+        || res.events.filter((e) => e.type === "delta" && "text" in e).map((e) => e.text).join("");
+    const reply = (text.trim() || lastNote || (lastDef || lastPatch ? "已更新工作流(见画布)。" : "已记录,请继续补充。"));
+    // 有提案被接受 → 正常返回(中途被拒过也算自我修复成功)。一次都没被接受但拒过 → 显式失败。
+    const rejected = !lastDef && !lastPatch && rejectedAttempts > 0
+        ? { attempts: rejectedAttempts, errors: lastRejectErrors }
+        : undefined;
+    return { reply, def: lastDef, patch: lastPatch, trigger: lastTrigger, ...(rejected ? { rejected } : {}) };
+}

package/dist/permissions.d.ts

@@ -0,0 +1,2 @@
+export { PERMISSION_MODES, } from "./runtime/ports/permission-contracts.js";
+export type { ApprovalRequest, ApprovalResponse, PermissionAllowResult, PermissionApprovalResolver, PermissionAskResult, PermissionBehavior, PermissionConfig, PermissionDecisionReason, PermissionDenyResult, PermissionMetadataResolver, PermissionMode, PermissionResult, PermissionRuleEnginePort, PermissionRuleEntry, ToolPermissionCheckInput, } from "./runtime/ports/permission-contracts.js";

package/dist/permissions.js

@@ -1 +1 @@
-var e=["default","auto","full_access"];export{e as PERMISSION_MODES};
+export { PERMISSION_MODES, } from "./runtime/ports/permission-contracts.js";

package/dist/permissions.public-api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/permissions.public-api.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { PERMISSION_MODES, } from "./permissions.js";
+describe("public permissions contract", () => {
+    it("exports the cc-aligned permission modes and decision contract for hosts", () => {
+        const modes = PERMISSION_MODES;
+        expect(modes).toEqual([
+            "default",
+            "auto",
+            "full_access",
+        ]);
+        const config = {
+            mode: "auto",
+        };
+        const check = {
+            toolName: "execute_command",
+            meta: { riskLevel: "system", requiresApproval: true },
+        };
+        expect(config.mode).toBe("auto");
+        expect(check.meta?.riskLevel).toBe("system");
+    });
+    it("declares a stable qlogicagent/permissions package subpath", () => {
+        const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        expect(packageJson.exports?.["./permissions"]).toEqual({
+            types: "./dist/types/permissions.d.ts",
+            default: "./dist/permissions.js",
+        });
+        expect(packageJson.typesVersions?.["*"]?.permissions).toEqual([
+            "./dist/types/permissions.d.ts",
+        ]);
+    });
+});

package/dist/pet-contracts.d.ts

@@ -0,0 +1 @@
+export { PETDEX_ANIMATION_IDS, PETDEX_ATLAS_CONTRACT, PETDEX_SCHEMA, PETDEX_VALIDATION_SCHEMA, type PetdexAnimation, type PetdexAnimationId, type PetdexAnimationMap, type PetdexAssetManifest, type PetdexAssetSummary, type PetdexAssetValidation, type PetdexAtlasManifest, } from "./protocol/wire/pet-contracts.js";

package/dist/pet-contracts.js

@@ -1 +1 @@
-var e=["idle","running-right","running-left","waving","jumping","failed","waiting","running","review"],t="qlogic.petdex.asset.v1",i="qlogic.petdex.validation.v1",n={format:"webp",columns:8,rows:9,frameCount:72,cellWidth:192,cellHeight:208,width:1536,height:1872};export{e as PETDEX_ANIMATION_IDS,n as PETDEX_ATLAS_CONTRACT,t as PETDEX_SCHEMA,i as PETDEX_VALIDATION_SCHEMA};
+export { PETDEX_ANIMATION_IDS, PETDEX_ATLAS_CONTRACT, PETDEX_SCHEMA, PETDEX_VALIDATION_SCHEMA, } from "./protocol/wire/pet-contracts.js";

package/dist/protocol/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Protocol barrel — centralized re-export of all agent RPC contracts.
+ *
+ * Import from here: `import type { NotificationMethod, RpcMethod } from "../protocol/index.js";`
+ */
+export * from "./notifications.js";
+export * from "./methods.js";

package/dist/protocol/index.js

@@ -0,0 +1,7 @@
+/**
+ * Protocol barrel — centralized re-export of all agent RPC contracts.
+ *
+ * Import from here: `import type { NotificationMethod, RpcMethod } from "../protocol/index.js";`
+ */
+export * from "./notifications.js";
+export * from "./methods.js";