nolo-cli 0.1.21 → 0.1.23

package/ai/skills/skillDocProtocol.ts

@@ -47,12 +47,30 @@ export interface SkillEvalConfig {
   cases: SkillEvalCase[];
 }
 
+export interface WorkflowReferenceConfig {
+  version: "0.1";
+  kind: "workflow";
+  id?: string;
+  name: string;
+  description: string;
+  defaultAgent?: string;
+  inputs?: string[];
+  recommendedTools?: string[];
+  requiredTools?: string[];
+  requiredOutputs?: string[];
+  gates?: string[];
+  budgetTier?: SkillBudgetTier;
+  contextStrategy?: string;
+  failureProtocol?: string;
+}
+
 export interface PageSkillMetadata {
   kind?: SkillDocKind;
   requiredSkills?: string[];
   recommendedSkills?: string[];
   skillConfig?: SkillDocConfig;
   evalConfig?: SkillEvalConfig;
+  workflowConfig?: WorkflowReferenceConfig;
 }
 
 export interface ParsedSkillDocProtocol {
@@ -71,6 +89,7 @@ export interface ParsedExternalSkillMarkdown {
 
 const SKILL_CONFIG_BLOCK = "skill-config";
 const EVAL_CONFIG_BLOCK = "eval-config";
+const WORKFLOW_CONFIG_BLOCK = "workflow-config";
 
 const normalizeStringArray = (value: unknown): string[] | undefined => {
   if (!Array.isArray(value)) return undefined;
@@ -200,6 +219,49 @@ const normalizeEvalConfig = (value: unknown): SkillEvalConfig | undefined => {
     : undefined;
 };
 
+const normalizeWorkflowConfig = (value: unknown): WorkflowReferenceConfig | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const record = value as Record<string, unknown>;
+  const name =
+    typeof record.name === "string" && record.name.trim()
+      ? record.name.trim()
+      : "";
+  const description =
+    typeof record.description === "string" && record.description.trim()
+      ? record.description.trim()
+      : "";
+  if (!name || !description) return undefined;
+  const budgetTier = normalizeSkillEnumValue("budgetTier", record.budgetTier);
+  return {
+    version: "0.1",
+    kind: "workflow",
+    id:
+      typeof record.id === "string" && record.id.trim()
+        ? record.id.trim()
+        : undefined,
+    name,
+    description,
+    defaultAgent:
+      typeof record.defaultAgent === "string" && record.defaultAgent.trim()
+        ? record.defaultAgent.trim()
+        : undefined,
+    inputs: normalizeStringArray(record.inputs),
+    recommendedTools: normalizeStringArray(record.recommendedTools),
+    requiredTools: normalizeStringArray(record.requiredTools),
+    requiredOutputs: normalizeStringArray(record.requiredOutputs),
+    gates: normalizeStringArray(record.gates),
+    budgetTier,
+    contextStrategy:
+      typeof record.contextStrategy === "string" && record.contextStrategy.trim()
+        ? record.contextStrategy.trim()
+        : undefined,
+    failureProtocol:
+      typeof record.failureProtocol === "string" && record.failureProtocol.trim()
+        ? record.failureProtocol.trim()
+        : undefined,
+  };
+};
+
 const normalizePageSkillMetadata = (
   value: unknown,
   fallbackTools?: string[]
@@ -214,17 +276,22 @@ const normalizePageSkillMetadata = (
     recommendedSkills: normalizeStringArray(record.recommendedSkills),
     skillConfig: normalizeSkillConfig(record.skillConfig, fallbackTools),
     evalConfig: normalizeEvalConfig(record.evalConfig),
+    workflowConfig: normalizeWorkflowConfig(record.workflowConfig),
   };
 
   if (meta.skillConfig && !meta.kind) {
     meta.kind = "skill";
   }
+  if (meta.workflowConfig && !meta.kind) {
+    meta.kind = "instruction";
+  }
 
   return meta.kind ||
     meta.requiredSkills ||
     meta.recommendedSkills ||
     meta.skillConfig ||
-    meta.evalConfig
+    meta.evalConfig ||
+    meta.workflowConfig
     ? meta
     : undefined;
 };
@@ -268,9 +335,13 @@ export const parseSkillDocProtocol = (
   const source = typeof markdown === "string" ? markdown : "";
   const skillBlock = parseYamlObject(extractCommentBlock(source, SKILL_CONFIG_BLOCK));
   const evalBlock = parseYamlObject(extractCommentBlock(source, EVAL_CONFIG_BLOCK));
+  const workflowBlock = parseYamlObject(extractCommentBlock(source, WORKFLOW_CONFIG_BLOCK));
   const cleanedContent = removeCommentBlock(
-    removeCommentBlock(source, SKILL_CONFIG_BLOCK),
-    EVAL_CONFIG_BLOCK
+    removeCommentBlock(
+      removeCommentBlock(source, SKILL_CONFIG_BLOCK),
+      EVAL_CONFIG_BLOCK
+    ),
+    WORKFLOW_CONFIG_BLOCK
   )
     .replace(/\n{3,}/g, "\n\n")
     .trim();
@@ -292,6 +363,7 @@ export const parseSkillDocProtocol = (
           }
         : {}),
       ...(evalBlock ? { evalConfig: evalBlock } : {}),
+      ...(workflowBlock ? { workflowConfig: workflowBlock } : {}),
     },
     fallbackTools
   );
@@ -364,15 +436,35 @@ export const buildEvalConfigComment = (config: SkillEvalConfig): string =>
     cases: config.cases,
   })}\n-->`;
 
+export const buildWorkflowConfigComment = (config: WorkflowReferenceConfig): string =>
+  `<!-- ${WORKFLOW_CONFIG_BLOCK}\n${yamlBlock({
+    version: config.version,
+    kind: config.kind,
+    ...(config.id ? { id: config.id } : {}),
+    name: config.name,
+    description: config.description,
+    ...(config.defaultAgent ? { defaultAgent: config.defaultAgent } : {}),
+    ...(config.inputs?.length ? { inputs: config.inputs } : {}),
+    ...(config.recommendedTools?.length ? { recommendedTools: config.recommendedTools } : {}),
+    ...(config.requiredTools?.length ? { requiredTools: config.requiredTools } : {}),
+    ...(config.requiredOutputs?.length ? { requiredOutputs: config.requiredOutputs } : {}),
+    ...(config.gates?.length ? { gates: config.gates } : {}),
+    ...(config.budgetTier ? { budgetTier: config.budgetTier } : {}),
+    ...(config.contextStrategy ? { contextStrategy: config.contextStrategy } : {}),
+    ...(config.failureProtocol ? { failureProtocol: config.failureProtocol } : {}),
+  })}\n-->`;
+
 export const buildSkillDocMarkdown = (options: {
   body?: string;
   skillConfig: SkillDocConfig;
   evalConfig?: SkillEvalConfig;
+  workflowConfig?: WorkflowReferenceConfig;
 }): string => {
   const sections = [
     options.body?.trim() || "",
     buildSkillConfigComment(options.skillConfig),
     options.evalConfig ? buildEvalConfigComment(options.evalConfig) : "",
+    options.workflowConfig ? buildWorkflowConfigComment(options.workflowConfig) : "",
   ].filter(Boolean);
   return sections.join("\n\n").trim();
 };

package/ai/taskRun/taskRunProtocol.ts

@@ -193,6 +193,7 @@ export type TaskRunControlPolicy = {
   autonomy?: TaskRunAutonomy;
   nextWakeAt?: string;
   pausedReason?: string;
+  runtimeToolPolicy?: Record<string, unknown>;
   budget?: {
     dailyUsdLimit?: number;
     modelBudget?: Record<string, TaskRunBudgetRule>;

package/ai/tools/agent/agentTools.ts

@@ -28,6 +28,10 @@ import {
     streamParallelAgentsFunctionSchema,
     streamParallelAgentsFunc,
 } from "./streamParallelAgentsTool";
+import {
+    startAgentDialogFunctionSchema,
+    startAgentDialogFunc,
+} from "./startAgentDialogTool";
 import {
     createDialogFunctionSchema,
     createDialogFunc,
@@ -151,6 +155,19 @@ export const agentToolDefinitions: ToolDefinition[] = [
         behavior: "orchestrator",
         uiGroup: "agent",
     },
+    {
+        id: "startAgentDialog",
+        schema: startAgentDialogFunctionSchema,
+        executor: startAgentDialogFunc,
+        description: {
+            name: "startAgentDialog",
+            description:
+                "启动一个子 Agent dialog，返回 childDialogId，供调用方后续查询、接管或投影状态。",
+            category: "计划与编排",
+        },
+        behavior: "orchestrator",
+        uiGroup: "agent",
+    },
     {
         id: "createDialog",
         schema: createDialogFunctionSchema,

package/ai/tools/agent/startAgentDialogTool.ts

@@ -0,0 +1,53 @@
+export const startAgentDialogFunctionSchema = {
+  name: "startAgentDialog",
+  description:
+    "启动一个子 Agent dialog 并立即返回 childDialogId。用于通用 agent 派发/交接，不等待子 Agent 完成，也不替调用方决定任务状态。",
+  parameters: {
+    type: "object",
+    properties: {
+      targetAgentKey: {
+        type: "string",
+        description: "要启动的目标 Agent key。",
+      },
+      message: {
+        type: "string",
+        description: "发送给目标 Agent 的自然语言任务或上下文。",
+      },
+      parentDialogId: {
+        type: "string",
+        description: "可选。父 dialogId；未提供时使用当前 dialogId。",
+      },
+      subjectRefs: {
+        type: "array",
+        description: "可选。与本次子 dialog 相关的业务对象引用，保持行业中立。",
+        items: {
+          type: "object",
+          properties: {
+            kind: { type: "string" },
+            id: { type: "string" },
+            role: { type: "string" },
+          },
+          required: ["kind", "id"],
+        },
+      },
+      idempotencyKey: {
+        type: "string",
+        description: "可选。调用方用于去重的稳定 key；当前版本仅透传给运行上下文。",
+      },
+      serverBase: {
+        type: "string",
+        description:
+          "可选。目标 Agent 所在的 nolo server origin；跨域目标必须由服务端 AGENT_TOOL_ALLOWED_SERVER_BASES 放行。",
+      },
+      timeoutMs: {
+        type: "number",
+        description: "可选。子 Agent background run 的执行超时预算（毫秒）。",
+      },
+    },
+    required: ["targetAgentKey", "message"],
+  },
+};
+
+export async function startAgentDialogFunc(): Promise<never> {
+  throw new Error("startAgentDialog is a server-side agent tool. Use it through /api/agent/run.");
+}

package/ai/tools/modelUsageTools.ts

@@ -179,6 +179,11 @@ export const notifyUserFunctionSchema = {
         type: "string",
         description: "可选跳转链接。",
       },
+      targetUserId: {
+        type: "string",
+        description:
+          "可选目标用户 ID。默认通知当前用户；只有受信任的系统 agent 或管理员可以通知其他用户。",
+      },
     },
     required: ["title", "message"],
   },

package/client/agentRun.test.ts

@@ -7,6 +7,7 @@ import {
   runAgentTurn,
   shouldUseScriptBridge,
 } from "./agentRun";
+import { NOLO_PROJECT_MANAGER_AGENT_KEY } from "../agentAliases";
 
 class CaptureOutput extends Writable {
   chunks: string[] = [];
@@ -131,6 +132,12 @@ describe("cli agent run client", () => {
     expect(requests[0]?.body.userInput).toContain("rowDbKey: row-b2e06f801f-01TASK");
     expect(requests[0]?.body.userInput).toContain("workItemId: frontend-filter");
     expect(requests[0]?.body.userInput).toContain("User task:\nFix the filter UI");
+    expect(requests[0]?.body.runtimeContext.taskRun).toEqual({
+      rowDbKey: "row-b2e06f801f-01TASK",
+      taskRunId: "taskrun-1",
+      workItemId: "frontend-filter",
+      artifactIds: ["artifact-1"],
+    });
   });
 
   test("records task-run completion after an HTTP agent run returns a dialog", async () => {
@@ -242,6 +249,42 @@ describe("cli agent run client", () => {
     expect(result).toEqual({ exitCode: 0, dialogId: "dialog-1" });
   });
 
+  test("records background task-run handoff as running instead of completed", async () => {
+    const output = new CaptureOutput();
+    const writebacks: any[] = [];
+
+    const result = await runAgentTurn({
+      agentName: "frontend-implementer",
+      agentKey: "agent-frontend",
+      serverUrl: "https://nolo.chat",
+      message: "Fix settings style FOUC",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      runtimeMode: "server",
+      background: true,
+      noStream: true,
+      taskRunContext: {
+        rowDbKey: "row-b2e06f801f-01TASK",
+        workItemId: "self",
+      },
+      taskRunRecorder: async (args) => {
+        writebacks.push(args);
+      },
+      output,
+      scriptPathExists: () => false,
+      fetchImpl: async () => {
+        return Response.json({ dialogId: "dialog-bg", status: "pending" }, { status: 202 });
+      },
+    });
+
+    expect(result).toEqual({ exitCode: 0, dialogId: "dialog-bg" });
+    expect(writebacks).toHaveLength(1);
+    expect(writebacks[0]).toMatchObject({
+      status: "running",
+      dialogId: "dialog-bg",
+    });
+  });
+
   test("runs forced local turns through the injected runtime adapter without HTTP", async () => {
     const output = new CaptureOutput();
     const result = await runAgentTurn({
@@ -521,6 +564,58 @@ describe("cli agent run client", () => {
     });
   });
 
+  test("records local background task-run handoff as running instead of completed", async () => {
+    const output = new CaptureOutput();
+    const writebacks: any[] = [];
+
+    const result = await runAgentTurn({
+      agentName: "frontend",
+      agentKey: "frontend-local",
+      serverUrl: "https://nolo.chat",
+      message: "inspect repo in background",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      output,
+      runtimeMode: "local",
+      background: true,
+      taskRunContext: {
+        rowDbKey: "row-b2e06f801f-01TASK",
+        workItemId: "self",
+      },
+      taskRunRecorder: async (args) => {
+        writebacks.push(args);
+      },
+      localRuntimeAdapter: {
+        host: "cli",
+        capabilities: ["local-provider", "local-persistence"],
+        loadAgentConfig: async (agentRef) => ({
+          key: agentRef,
+          name: "Frontend",
+          prompt: "Fix UI",
+          model: "fake-local",
+        }),
+        loadDialogHistory: async () => [],
+        saveTurn: async () => ({ dialogId: "dialog-local-bg" }),
+        resolveProvider: async () => ({
+          model: "fake-local",
+          complete: async () => ({ content: "accepted locally", model: "fake-local" }),
+        }),
+        executeTool: async () => {
+          throw new Error("no tools expected");
+        },
+      },
+      scriptPathExists: () => false,
+    });
+
+    expect(result).toEqual({ exitCode: 0, dialogId: "dialog-local-bg" });
+    expect(writebacks).toHaveLength(1);
+    expect(writebacks[0]).toMatchObject({
+      status: "running",
+      dialogId: "dialog-local-bg",
+    });
+    expect(writebacks[0].resultSummary).toBeUndefined();
+  });
+
   test("auto mode prefers a working local runtime before HTTP", async () => {
     const output = new CaptureOutput();
     const httpCalls: string[] = [];
@@ -571,7 +666,7 @@ describe("cli agent run client", () => {
 
     const result = await runAgentTurn({
       agentName: "pm",
-      agentKey: "nolo-project-manager",
+      agentKey: "agent-custom-platform-tools",
       serverUrl: "https://nolo.chat",
       message: "write task rows",
       scriptDir: "C:/missing/scripts",
@@ -608,13 +703,112 @@ describe("cli agent run client", () => {
 
     expect(result).toEqual({ exitCode: 0, dialogId: "dialog-server" });
     expect(httpCalls).toHaveLength(1);
-    expect(httpCalls[0]?.body.agentKey).toBe("nolo-project-manager");
+    expect(httpCalls[0]?.body.agentKey).toBe("agent-custom-platform-tools");
     expect(output.text()).toContain("auto runtime: skipping local runtime");
     expect(output.text()).toContain("queryTableRows, addTableRow, updateTableRow");
     expect(output.text()).toContain("pm -> working");
     expect(output.text()).toContain("pm > server ok");
   });
 
+  test("auto mode skips local runtime for server platform tools declared by runtime policy", async () => {
+    const output = new CaptureOutput();
+    const httpCalls: Array<{ url: string; body: any }> = [];
+
+    const result = await runAgentTurn({
+      agentName: "pm",
+      agentKey: "agent-policy-platform-tools",
+      serverUrl: "https://nolo.chat",
+      message: "query task rows",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      output,
+      runtimeMode: "auto",
+      localRuntimeAdapter: {
+        host: "cli",
+        capabilities: ["leveldb-agent-config", "local-provider", "local-tools"],
+        loadAgentConfig: async (agentRef) => ({
+          key: agentRef,
+          name: "PM",
+          prompt: "Manage task rows",
+          model: "fake-local",
+          runtimeToolPolicy: {
+            version: 1,
+            agentTools: ["queryTableRows", "taskRun"],
+            runtimeTools: ["execShell"],
+          },
+        }),
+        loadDialogHistory: async () => [],
+        saveTurn: async () => {
+          throw new Error("local runtime should be skipped");
+        },
+        resolveProvider: async () => {
+          throw new Error("local provider should be skipped");
+        },
+        executeTool: async () => {
+          throw new Error("local tools should be skipped");
+        },
+      },
+      scriptPathExists: () => false,
+      fetchImpl: async (url, init) => {
+        httpCalls.push({ url: String(url), body: JSON.parse(String(init?.body)) });
+        return Response.json({ content: "server ok", dialogId: "dialog-server-policy" });
+      },
+    });
+
+    expect(result).toEqual({ exitCode: 0, dialogId: "dialog-server-policy" });
+    expect(httpCalls).toHaveLength(1);
+    expect(httpCalls[0]?.body.agentKey).toBe("agent-policy-platform-tools");
+    expect(output.text()).toContain("auto runtime: skipping local runtime");
+    expect(output.text()).toContain("queryTableRows, taskRun");
+  });
+
+  test("auto mode skips known platform agents when local config cannot be read", async () => {
+    const output = new CaptureOutput();
+    const httpCalls: Array<{ url: string; body: any }> = [];
+
+    const result = await runAgentTurn({
+      agentName: "nolo-project-manager",
+      agentKey: NOLO_PROJECT_MANAGER_AGENT_KEY,
+      serverUrl: "https://us.nolo.chat",
+      message: "write task rows",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123", OPENAI_API_KEY: "local-provider-present" },
+      output,
+      runtimeMode: "auto",
+      localRuntimeAdapter: {
+        host: "cli",
+        capabilities: ["leveldb-agent-config", "local-provider", "local-tools"],
+        loadAgentConfig: async () => {
+          throw new Error("Database failed to open: LOCK");
+        },
+        loadDialogHistory: async () => {
+          throw new Error("local runtime should be skipped");
+        },
+        saveTurn: async () => {
+          throw new Error("local runtime should be skipped");
+        },
+        resolveProvider: async () => {
+          throw new Error("local provider should be skipped");
+        },
+        executeTool: async () => {
+          throw new Error("local tools should be skipped");
+        },
+      },
+      scriptPathExists: () => false,
+      fetchImpl: async (url, init) => {
+        httpCalls.push({ url: String(url), body: JSON.parse(String(init?.body)) });
+        return Response.json({ content: "server ok", dialogId: "dialog-server" });
+      },
+    });
+
+    expect(result).toEqual({ exitCode: 0, dialogId: "dialog-server" });
+    expect(httpCalls).toHaveLength(1);
+    expect(httpCalls[0]?.body.agentKey).toBe(NOLO_PROJECT_MANAGER_AGENT_KEY);
+    expect(output.text()).toContain("known platform agent");
+    expect(output.text()).toContain("nolo-project-manager -> working");
+    expect(output.text()).toContain("nolo-project-manager > server ok");
+  });
+
   test("builds the default local adapter when env requests local mode", async () => {
     const output = new CaptureOutput();
     const builtModes: string[] = [];
@@ -685,11 +879,67 @@ describe("cli agent run client", () => {
     });
 
     expect(result).toEqual({ exitCode: 0, dialogId: "dialog-stream" });
-    expect(output.text()).toContain("nolo -> working");
-    expect(output.text()).toContain("nolo > 你好");
-  });
-
-  test("prints an auth hint when installed without repo scripts or AUTH_TOKEN", async () => {
+    expect(output.text()).toContain("nolo -> working");
+    expect(output.text()).toContain("nolo > 你好");
+  });
+
+  test("returns a recoverable dialog when a server stream drops after dialog creation", async () => {
+    const output = new CaptureOutput();
+
+    const result = await runAgentTurn({
+      agentName: "nolo",
+      agentKey: "agent-pub-test",
+      serverUrl: "https://nolo.chat",
+      message: "hello",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      output,
+      scriptPathExists: () => false,
+      fetchImpl: async () => {
+        let sent = false;
+        return new Response(
+          new ReadableStream({
+            pull(controller) {
+              const encoder = new TextEncoder();
+              if (!sent) {
+                sent = true;
+                controller.enqueue(
+                  encoder.encode(
+                    [
+                      `data: ${JSON.stringify({
+                        type: "dialog",
+                        dialogId: "dialog-recoverable",
+                        status: "running",
+                      })}`,
+                      "",
+                      `data: ${JSON.stringify({ type: "text", content: "partial" })}`,
+                      "",
+                    ].join("\n")
+                  )
+                );
+                return;
+              }
+              controller.error(new Error("socket closed"));
+            },
+          }),
+          {
+            status: 200,
+            headers: { "Content-Type": "text/event-stream" },
+          }
+        );
+      },
+    });
+
+    expect(result).toEqual({
+      exitCode: 0,
+      dialogId: "dialog-recoverable",
+      streamInterrupted: true,
+    });
+    expect(output.text()).toContain("dialog dialog-recoverable was created");
+    expect(output.text()).toContain("read the dialog before retrying");
+  });
+
+  test("prints an auth hint when installed without repo scripts or AUTH_TOKEN", async () => {
     const output = new CaptureOutput();
 
     const result = await runAgentTurn({