@zibby/skills 0.1.34 → 0.1.35

package/dist/workflow-builder.d.ts

@@ -0,0 +1,245 @@
+export namespace workflowBuilderSkill {
+    export let id: string;
+    export let description: string;
+    export let envKeys: any[];
+    export { PROMPT_FRAGMENT as promptFragment };
+    export let tools: ({
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                nodes: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            name: {
+                                type: string;
+                                description: string;
+                            };
+                            description: {
+                                type: string;
+                                description: string;
+                            };
+                            inputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                            outputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                edges: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            from: {
+                                type: string;
+                                description: string;
+                            };
+                            to: {
+                                type: string;
+                                description: string;
+                            };
+                            condition: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                spec: {
+                    type: string;
+                    description: string;
+                    properties: {
+                        name: {
+                            type: string;
+                        };
+                        description: {
+                            type: string;
+                        };
+                        nodes: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                        edges: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                workflowName: {
+                    type: string;
+                    description: string;
+                };
+                nodeName: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                inputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                outputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                name?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                projectId: {
+                    type: string;
+                    description: string;
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                topic: {
+                    type: string;
+                    description: string;
+                };
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+            };
+            required?: undefined;
+        };
+    })[];
+    export function handleToolCall(name: any, args: any, context: any): Promise<string>;
+    export function resolve(): any;
+}
+declare const PROMPT_FRAGMENT: "## Workflow Builder\n\nYou can help users build custom AI workflows using the Zibby workflow framework.\n\n### What makes Zibby workflows different\nEach node invokes a **real AI agent** (Cursor, Claude, Codex, or Gemini) \u2014 not a thin LLM API wrapper.\nThat means every node has full agent capabilities: tool use, MCP servers (browser, GitHub, Jira, Slack),\nmulti-turn reasoning, and structured output validation via Zod schemas.\n\nKey differentiators:\n- **Agent-powered nodes** \u2014 each step runs a full AI agent (cursor-agent, claude, codex, gemini CLI) with tool access and MCP skills, not a simple chat completion call.\n- **Structured output** \u2014 every node declares a Zod schema; the framework validates and parses the agent's response automatically.\n- **Conditional routing** \u2014 edges can branch on agent-produced fields (e.g., `state.triage.priority === 'critical'`), enabling intelligent decision graphs.\n- **MCP skill injection** \u2014 nodes declare `skills: [SKILLS.BROWSER, SKILLS.GITHUB]` and the framework spins up the right MCP servers automatically.\n- **Deploy anywhere** \u2014 `zibby deploy` pushes to Zibby Cloud with an API trigger; or self-host with `zibby start`.\n- **State accumulation** \u2014 each node's validated output is stored under its name in `state` (e.g., `state.classify_ticket`), so downstream nodes can reference upstream results.\n\n### What is a workflow?\nA directed graph of nodes (AI agent steps) connected by edges. Each node has:\n- `name` \u2014 unique identifier (snake_case)\n- `prompt` \u2014 function that receives state and returns the prompt string sent to the agent\n- `outputSchema` \u2014 Zod schema defining the structured output the agent must return\n- `skills` (optional) \u2014 array of MCP skill IDs the node needs (e.g., `SKILLS.BROWSER`, `SKILLS.GITHUB`)\n- `timeout` (optional) \u2014 max execution time in ms (default: 300000)\n- `model` (optional) \u2014 override the model for this node (e.g., `'claude-opus-4'`)\n\n### File structure\n```\n.zibby/workflows/<name>/\n\u251C\u2500\u2500 graph.mjs          \u2014 WorkflowAgent subclass with buildGraph()\n\u251C\u2500\u2500 nodes/\n\u2502   \u251C\u2500\u2500 index.mjs      \u2014 barrel export for all nodes\n\u2502   \u2514\u2500\u2500 <node>.mjs     \u2014 one file per node\n\u2514\u2500\u2500 workflow.json       \u2014 manifest (name, description, triggers)\n```\n\n### Node pattern\n```javascript\nimport { z, SKILLS } from '@zibby/core';\n\nconst OutputSchema = z.object({\n  summary: z.string().describe('Brief summary'),\n  items: z.array(z.string()).describe('List of extracted items'),\n  needsReview: z.boolean().describe('Whether a human should review this'),\n});\n\nexport const myNode = {\n  name: 'my_node',\n  skills: [SKILLS.GITHUB],  // optional \u2014 framework injects MCP servers\n  timeout: 120000,           // optional \u2014 2 min timeout\n  prompt: (state) => \\`You are analyzing a pull request.\n\nInput:\n\\${JSON.stringify(state.input || {}, null, 2)}\n\nReturn a JSON object matching the schema.\\`,\n  outputSchema: OutputSchema,\n};\n```\n\n### Graph pattern\n```javascript\nimport { WorkflowAgent, WorkflowGraph } from '@zibby/core';\nimport { classifyNode, routeNode } from './nodes/index.mjs';\n\nexport class MyWorkflow extends WorkflowAgent {\n  buildGraph() {\n    const graph = new WorkflowGraph();\n    graph.addNode('classify', classifyNode);\n    graph.addNode('route', routeNode);\n    graph.setEntryPoint('classify');\n    graph.addEdge('classify', 'route');\n    graph.addEdge('route', 'END');\n    return graph;\n  }\n\n  async onComplete(result) {\n    // Post-execution hook \u2014 save artifacts, notify, etc.\n    console.log('Workflow complete:', result.success);\n  }\n}\n```\n\nConditional edges: `graph.addConditionalEdges('node', (state) => state.node.priority === 'high' ? 'escalate' : 'notify')`\n\n### Available SKILLS constants\nImport from `@zibby/core`: `SKILLS.BROWSER`, `SKILLS.MEMORY`, `SKILLS.GITHUB`, `SKILLS.JIRA`, `SKILLS.SLACK`, `SKILLS.RUNNER`\n\n### Deep documentation\nCall `explore_framework_docs` to read detailed framework docs on demand. Use it for:\n- Advanced patterns (middleware, parallel nodes, state schemas)\n- Deployment & cloud triggers\n- CLI commands reference\n- Integration details (Jira, GitHub, etc.)\nCall with no arguments to see all available topics.\n\n### How to use the builder tools\n1. For complex workflows, call `explore_framework_docs(\"custom-workflows\")` first to learn advanced patterns.\n2. Ask the user what their workflow should do, what input it receives, and what steps are needed.\n3. Call `design_workflow` with the structured spec for the user to review.\n4. Once approved, call `build_workflow` to generate real code on disk (uses the configured agent for high-quality code generation).\n5. Remind the user: `zibby start <name>` to test locally, `zibby deploy <name> --project <id>` to deploy to cloud, `zibby logs --workflow <name>` to tail logs.\n\n### Important\n- Each node prompt should be detailed and specific \u2014 tell the AI agent exactly what to do and what format to return.\n- Zod schemas MUST use .describe() on every field so the agent knows what each field means.\n- Node names must be snake_case (e.g., classify_ticket, generate_report).\n- Workflow names must be kebab-case (e.g., ticket-triage, pr-review).\n- State flows through: each node's validated output is stored under its name in state (e.g., state.classify_ticket).\n- Downstream nodes reference upstream outputs in their prompt function (e.g., \\`\\${JSON.stringify(state.classify_ticket, null, 2)}\\`).\n- Nodes can declare skills to get MCP tool access \u2014 the framework handles server lifecycle automatically.";
+export {};

package/package.json

@@ -1,31 +1,78 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./bin/mcp-sentry.mjs": "./bin/mcp-sentry.mjs",
     "./bin/mcp-lark.mjs": "./bin/mcp-lark.mjs",
     "./bin/mcp-slack.mjs": "./bin/mcp-slack.mjs",
-    "./browser": "./dist/browser.js",
-    "./jira": "./dist/jira.js",
-    "./github": "./dist/github.js",
-    "./gitlab": "./dist/gitlab.js",
-    "./linear": "./dist/linear.js",
-    "./plane": "./dist/plane.js",
-    "./slack": "./dist/slack.js",
-    "./lark": "./dist/lark.js",
-    "./memory": "./dist/memory.js",
-    "./function": "./dist/function-skill.js",
-    "./integrations": "./dist/integrations.js",
-    "./report": "./dist/report.js",
-    "./llm-billing": "./dist/llm-billing.js",
-    "./sentry": "./dist/sentry.js"
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./jira": {
+      "types": "./dist/jira.d.ts",
+      "default": "./dist/jira.js"
+    },
+    "./github": {
+      "types": "./dist/github.d.ts",
+      "default": "./dist/github.js"
+    },
+    "./gitlab": {
+      "types": "./dist/gitlab.d.ts",
+      "default": "./dist/gitlab.js"
+    },
+    "./linear": {
+      "types": "./dist/linear.d.ts",
+      "default": "./dist/linear.js"
+    },
+    "./plane": {
+      "types": "./dist/plane.d.ts",
+      "default": "./dist/plane.js"
+    },
+    "./slack": {
+      "types": "./dist/slack.d.ts",
+      "default": "./dist/slack.js"
+    },
+    "./lark": {
+      "types": "./dist/lark.d.ts",
+      "default": "./dist/lark.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "default": "./dist/memory.js"
+    },
+    "./function": {
+      "types": "./dist/function-skill.d.ts",
+      "default": "./dist/function-skill.js"
+    },
+    "./integrations": {
+      "types": "./dist/integrations.d.ts",
+      "default": "./dist/integrations.js"
+    },
+    "./report": {
+      "types": "./dist/report.d.ts",
+      "default": "./dist/report.js"
+    },
+    "./llm-billing": {
+      "types": "./dist/llm-billing.d.ts",
+      "default": "./dist/llm-billing.js"
+    },
+    "./sentry": {
+      "types": "./dist/sentry.d.ts",
+      "default": "./dist/sentry.js"
+    }
   },
   "scripts": {
-    "build": "node ../scripts/build.mjs",
+    "build": "node ../scripts/build.mjs && npm run build:types",
+    "build:types": "tsc -p tsconfig.types.json",
     "prepack": "node scripts/copy-docs.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix ."
@@ -58,8 +105,8 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@zibby/agent-workflow": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@zibby/agent-workflow": "^0.3.0",
     "better-sqlite3": "^12.6.2",
     "mem0ai": "npm:@zibby/mem0ai@^3.0.5",
     "zod": "^3.23.0 || ^4.0.0"
@@ -75,6 +122,7 @@
     "@eslint/js": "^10.0.1",
     "esbuild": "^0.28.0",
     "eslint": "^10.0.2",
-    "globals": "^17.4.0"
+    "globals": "^17.4.0",
+    "typescript": "^5.9.3"
   }
 }