bluekiwi 0.1.6 → 0.2.0

package/dist/assets/mcp/server.js

@@ -122,7 +122,9 @@ const tools = [
         session_meta: { type: "string" },
         target: { type: "object" },
     }, ["workflow_id"]),
-    tool("execute_step", "Submit the result for the current workflow step", {
+    tool("execute_step", "Submit the result for the current workflow step. " +
+        "IMPORTANT: If the response contains next_action='wait_for_human_approval', " +
+        "you MUST call request_approval next and then STOP — do NOT call advance until a human approves.", {
         task_id: { type: "number" },
         node_id: { type: "number" },
         output: { type: "string" },
@@ -137,10 +139,23 @@ const tools = [
         user_name: { type: "string" },
         model_id: { type: "string" },
     }, ["task_id", "node_id", "output", "status"]),
-    tool("advance", "Advance a task to the next step or inspect the current step", {
+    tool("advance", "Advance a task to the next step, or use peek=true to inspect the current step without advancing. " +
+        "WARNING: Do NOT call advance if execute_step returned next_action='wait_for_human_approval'. " +
+        "In that case, call request_approval and wait. The server will reject advance with 403 until a human approves.", {
         task_id: { type: "number" },
         peek: { type: "boolean" },
     }, ["task_id"]),
+    tool("request_approval", "Signal that the current step is complete and human approval is needed before proceeding. " +
+        "Call this after execute_step returns next_action='wait_for_human_approval'. " +
+        "After calling this, stop and wait — do NOT call advance until the human approves.", {
+        task_id: { type: "number" },
+        message: { type: "string" },
+    }, ["task_id"]),
+    tool("approve_step", "Approve the current HITL step on behalf of the human, unlocking advance. " +
+        "ONLY call this when the human explicitly invokes /bk-approve and confirms approval. " +
+        "Never call this autonomously — it must be a deliberate human action.", {
+        task_id: { type: "number" },
+    }, ["task_id"]),
     tool("heartbeat", "Append progress information for a running task step", {
         task_id: { type: "number" },
         node_id: { type: "number" },
@@ -174,6 +189,45 @@ const tools = [
         task_id: { type: "number" },
     }, ["task_id"]),
     tool("list_credentials", "List credentials available to the current user"),
+    tool("create_credential", "Create a new credential set (API key, token, etc.). Credentials must be placed in a private folder; they cannot live in public folders. Defaults to the caller's My Workspace if folder_id is omitted. Pass secrets as a JSON-serialisable object.", {
+        service_name: { type: "string" },
+        description: { type: "string" },
+        secrets: { type: "object" },
+        folder_id: { type: "number" },
+    }, ["service_name"]),
+    tool("update_credential", "Update an existing credential. Pass only the fields you want to change. Replacing secrets overwrites the entire secrets object.", {
+        credential_id: { type: "number" },
+        service_name: { type: "string" },
+        description: { type: "string" },
+        secrets: { type: "object" },
+        folder_id: { type: "number" },
+    }, ["credential_id"]),
+    tool("delete_credential", "Delete a credential. Fails with 409 if any instruction references this credential.", {
+        credential_id: { type: "number" },
+    }, ["credential_id"]),
+    tool("list_instructions", "List instruction templates visible to the current user. Optionally filter by folder_id.", {
+        folder_id: { type: "number" },
+    }),
+    tool("create_instruction", "Create a new instruction template. agent_type defaults to 'general'. priority is an integer (higher = more important). To reference a credential, include the service_name from list_credentials in the content text — actual credential binding happens at the workflow node level via create_workflow/update_workflow.", {
+        title: { type: "string" },
+        content: { type: "string" },
+        agent_type: { type: "string" },
+        tags: { type: "array" },
+        priority: { type: "number" },
+        folder_id: { type: "number" },
+    }, ["title"]),
+    tool("update_instruction", "Update an existing instruction template. Pass only the fields you want to change. Set is_active=false to soft-disable without deleting.", {
+        instruction_id: { type: "number" },
+        title: { type: "string" },
+        content: { type: "string" },
+        agent_type: { type: "string" },
+        tags: { type: "array" },
+        priority: { type: "number" },
+        is_active: { type: "boolean" },
+    }, ["instruction_id"]),
+    tool("delete_instruction", "Delete an instruction template. Fails with 409 if any workflow node references this instruction.", {
+        instruction_id: { type: "number" },
+    }, ["instruction_id"]),
     tool("create_workflow", "Create a new workflow. Optionally place it in a specific folder_id (defaults to the caller's My Workspace).", {
         title: { type: "string" },
         description: { type: "string" },
@@ -292,6 +346,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 delete body.task_id;
                 return wrap(await client.request("POST", `/api/tasks/${taskId}/advance`, body));
             }
+            case "request_approval": {
+                const taskId = requireNumberArg(args, "task_id");
+                const body = { ...args };
+                delete body.task_id;
+                return wrap(await client.request("POST", `/api/tasks/${taskId}/request-approval`, body));
+            }
+            case "approve_step": {
+                const taskId = requireNumberArg(args, "task_id");
+                return wrap(await client.request("POST", `/api/tasks/${taskId}/approve`, {}));
+            }
             case "heartbeat": {
                 const taskId = requireNumberArg(args, "task_id");
                 const body = { ...args };
@@ -336,6 +400,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "list_credentials":
                 return wrap(await client.request("GET", "/api/credentials"));
+            case "create_credential":
+                return wrap(await client.request("POST", "/api/credentials", args));
+            case "update_credential": {
+                const credentialId = requireNumberArg(args, "credential_id");
+                const body = { ...args };
+                delete body.credential_id;
+                return wrap(await client.request("PUT", `/api/credentials/${credentialId}`, body));
+            }
+            case "delete_credential": {
+                const credentialId = requireNumberArg(args, "credential_id");
+                return wrap(await client.request("DELETE", `/api/credentials/${credentialId}`));
+            }
+            case "list_instructions": {
+                const qs = new URLSearchParams();
+                if (typeof args.folder_id === "number")
+                    qs.set("folder_id", String(args.folder_id));
+                const suffix = qs.toString() ? `?${qs.toString()}` : "";
+                return wrap(await client.request("GET", `/api/instructions${suffix}`));
+            }
+            case "create_instruction":
+                return wrap(await client.request("POST", "/api/instructions", args));
+            case "update_instruction": {
+                const instructionId = requireNumberArg(args, "instruction_id");
+                const body = { ...args };
+                delete body.instruction_id;
+                return wrap(await client.request("PUT", `/api/instructions/${instructionId}`, body));
+            }
+            case "delete_instruction": {
+                const instructionId = requireNumberArg(args, "instruction_id");
+                return wrap(await client.request("DELETE", `/api/instructions/${instructionId}`));
+            }
             case "create_workflow":
                 return wrap(await client.request("POST", "/api/workflows", args));
             case "update_workflow": {

package/dist/assets/skills/bk-approve/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: bk-approve
+description: BlueKiwi approval skill. Handles two approval scenarios — (1) gate steps where the agent asks the human a question, and (2) HITL steps where auto_advance=false and the agent has requested human approval before proceeding. This skill should be used when the user says "/bk-approve", "approve this", "approve step", "yes proceed", or wants to approve a pending step in a BlueKiwi workflow.
+user_invocable: true
+---
+
+# BlueKiwi Step Approval
+
+Handle pending approvals in a running workflow. Covers two scenarios:
+
+- **Gate step** (`node_type: gate`): Agent asked the human a question; collect the answer.
+- **HITL step** (`node_type: action`, `auto_advance: false`): Agent completed work and called `request_approval`; human reviews and approves before the workflow continues.
+
+## Argument Handling
+
+- `/bk-approve` → Inspect the current step and handle whichever scenario applies.
+- `/bk-approve <task_id>` → Load the pending step for the specified task.
+
+## Execution Steps
+
+### Step 1: Inspect Current Step
+
+Call `advance` with `peek: true` to inspect the current step and its log status.
+
+If no active task → show "No active task." and exit.
+
+Check `log_status` and `node_type` to determine scenario:
+
+| node_type     | log_status              | Scenario                                        |
+| ------------- | ----------------------- | ----------------------------------------------- |
+| `gate`        | any                     | Gate — collect human answer                     |
+| `action`      | `completed` / `success` | HITL — review agent output and approve          |
+| anything else | `pending` / `running`   | Not ready — tell user the step is still running |
+
+### Step 2a: Gate Step
+
+1. Show the gate question from `instruction`.
+2. Check `get_web_response` for a pre-submitted web response. If found, show it and ask to confirm.
+3. Collect decision via AskUserQuestion:
+   - header: "Gate decision"
+   - options: ["Approve (Recommended)", "Approve with edits", "Reject and revise", "Rewind to previous step"]
+4. Call `execute_step` with the decision as `output`, status `"success"`.
+5. Call `advance` to move to the next step and follow the auto_advance loop (see `/bk-next`).
+
+### Step 2b: HITL Step
+
+1. Show a summary of what the agent completed:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸ Awaiting Approval: {step title}
+━━━━━━━━━━━━━━━━━━━━━━━━━
+{brief summary of agent's output from task log}
+━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+2. Ask via AskUserQuestion:
+   - header: "Approve?"
+   - options: ["Approve — proceed to next step (Recommended)", "Reject — rewind to this step", "Rewind to earlier step"]
+
+3. **If Approved**:
+   - Call `approve_step(task_id=<id>)` MCP tool.
+   - Call `advance` to move to the next step.
+   - Follow the auto_advance loop (see `/bk-next`).
+
+4. **If Rejected**:
+   - Ask the user for the reason.
+   - Call `rewind` to return to this step so the agent can redo it.
+   - Tell the user: "Rewound to step {N}. Type `/bk-next` to retry."
+
+5. **If Rewind to earlier step**:
+   - Switch to `/bk-rewind` flow.
+
+## Notes
+
+- `approve_step` MCP tool handles authentication automatically using the configured API key.
+- After approving a HITL step, always follow the auto_advance loop — the next step may auto-proceed.
+- If `advance` still returns 403 after approval, wait a moment and retry — the approval write may not have propagated yet.

package/dist/assets/skills/bk-credential/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: bk-credential
+description: BlueKiwi credential management skill. Securely registers, updates, and deletes external service credentials (API keys, tokens) in BlueKiwi. This skill should be used when the user says "/bk-credential", "add credential", "register API key", or wants to manage credentials in BlueKiwi.
+user_invocable: true
+---
+
+# BlueKiwi Credential Management
+
+Securely manage external service credentials (API keys, tokens) on the BlueKiwi server.
+
+## Argument Handling
+
+- `/bk-credential` → Show action selection menu.
+- `/bk-credential add <service name>` → Start the add credential flow.
+- `/bk-credential list` → Show registered credentials list.
+
+## Security Principles
+
+<HARD-RULE>
+- Never print credential secret values to the user.
+- When editing, never display existing secrets. Accept new values and replace entirely.
+- Credentials must be stored in **private (personal) folders only**. Never store in public folders.
+</HARD-RULE>
+
+## Execution Steps
+
+### Step 0: Select Action
+
+If no argument, ask via AskUserQuestion:
+
+- header: "Credentials"
+- options: ["List", "Add new", "Edit", "Delete"]
+
+---
+
+### Action: List
+
+Call `list_credentials` and display results:
+
+```
+Registered Credentials
+━━━━━━━━━━━━━━━━━━━━━━━━━
+ID  Service Name      Description
+━━━━━━━━━━━━━━━━━━━━━━━━━
+1   openai            OpenAI API
+2   github            GitHub PAT
+━━━━━━━━━━━━━━━━━━━━━━━━━
+2 total
+```
+
+---
+
+### Action: Add New
+
+**Service name**: Ask via AskUserQuestion.
+
+**Folder selection**: Call `list_folders`, filter for private folders only, then ask via AskUserQuestion:
+
+- header: "Save folder"
+- "Which folder should this be stored in? (Only private folders shown)"
+- options: private folder list + "My Workspace (default)"
+
+**Secrets input**: Ask the user for key-value pairs:
+
+```
+Enter the credentials for <service name>.
+Format: KEY=VALUE (one per line)
+Example:
+  API_KEY=sk-xxxx
+  BASE_URL=https://api.example.com
+```
+
+Parse the input to build the secrets object.
+
+**Description** (optional): Accept a short description.
+
+**Confirm**: Ask via AskUserQuestion before registering:
+
+- header: "Confirm"
+- "Service: <service_name>\nKeys: <key list (values masked)>\nRegister?"
+- options: ["Register", "Cancel"]
+
+Call `create_credential`:
+
+```json
+{
+  "service_name": "<service name>",
+  "description": "<description>",
+  "secrets": { "KEY": "value", ... },
+  "folder_id": <folder id or omit>
+}
+```
+
+---
+
+### Action: Edit
+
+Call `list_credentials`, then ask which one to edit via AskUserQuestion.
+
+Ask what to change (AskUserQuestion):
+
+- options: ["Change service name", "Change description", "Replace secrets", "Cancel"]
+
+For "Replace secrets" → accept all new key-value pairs and replace entirely.
+
+Call `update_credential`:
+
+```json
+{
+  "credential_id": <id>,
+  "service_name": "<if changed>",
+  "description": "<if changed>",
+  "secrets": { ... }
+}
+```
+
+---
+
+### Action: Delete
+
+Call `list_credentials`, then ask which one to delete via AskUserQuestion.
+
+Confirm via AskUserQuestion:
+
+- header: "Confirm delete"
+- "Delete the '<service_name>' credential? This will fail if any workflow node references it."
+- options: ["Delete", "Cancel"]
+
+Call `delete_credential`. On 409 error (in use), inform the user which workflow is using it.
+
+---
+
+## Linking to Workflows
+
+Credentials are linked to workflow nodes via `credential_id`.
+
+When designing workflows (`/bk-design`, `/bk-improve`), set the credential on the node that calls an external API:
+
+```json
+{
+  "title": "Call External API",
+  "credential_id": <credential id>
+}
+```
+
+BlueKiwi automatically injects the secrets into that node at runtime.

package/dist/assets/skills/bk-design/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: bk-design
+description: BlueKiwi workflow design skill. Takes a natural language goal and designs a structured workflow, then registers it on the server. This skill should be used when the user says "/bk-design", "create workflow", "design new workflow", or wants to build a new BlueKiwi workflow from scratch.
+user_invocable: true
+---
+
+# BlueKiwi Workflow Design
+
+Design a structured workflow from a natural language goal and register it on the BlueKiwi server.
+
+## Argument Handling
+
+- `/bk-design` → Ask for the goal via AskUserQuestion.
+- `/bk-design <goal>` → Start designing from the provided goal.
+
+## Core Principles
+
+- One node = **one agent action**. Split overly large chunks.
+- `auto_advance: true` = proceeds without user intervention. Suitable for data collection and transformation steps.
+- `auto_advance: false` = requires user confirmation or judgment.
+- `node_type` must be either `"agent"` (agent execution) or `"gate"` (user decision).
+
+## Execution Steps
+
+### Step 1: Understand the Goal
+
+Extract the goal from arguments. If none, ask via AskUserQuestion:
+
+- header: "What to build?"
+- "What task would you like to automate? Please describe in detail."
+- options: ["Competitor analysis", "Code review", "Report generation", "Type my own"]
+
+If "Type my own" → accept free-text goal input.
+
+### Step 2: Check for Existing Workflows
+
+Call `list_workflows` to check for similar existing workflows.
+
+If a similar one is found, ask via AskUserQuestion:
+
+- header: "Existing workflow"
+- "'{title}' already exists. Create a new one or improve the existing one?"
+- options: ["Create new", "Improve existing (switch to /bk-improve)"]
+
+If "Improve existing" → switch to `/bk-improve` flow.
+
+### Step 3: Select Folder
+
+Call `list_folders` to get the folder list.
+
+Ask via AskUserQuestion:
+
+- header: "Save location"
+- "Which folder should this be saved in?"
+- options: folder name list (up to 4) + "My Workspace (default)"
+
+### Step 4: Design Workflow Structure
+
+Analyze the goal and design the nodes.
+
+**Node structure example:**
+
+```json
+{
+  "title": "Clarify Goal",
+  "instruction": "Analyze the user's stated goal and extract the 3 most important clarifying questions.",
+  "node_type": "agent",
+  "auto_advance": true,
+  "order": 1
+}
+```
+
+Show the design to the user:
+
+```
+Designed workflow: <title>
+━━━━━━━━━━━━━━━━━━━━━━━━━
+1. [Clarify Goal]     (auto)
+2. [Collect Data]     (auto)
+3. [Run Analysis]     (auto)
+4. [Review Results]   ← pauses here
+5. [Generate Report]  (auto)
+━━━━━━━━━━━━━━━━━━━━━━━━━
+5 steps total
+```
+
+Ask via AskUserQuestion:
+
+- header: "Confirm"
+- "Create the workflow with this structure?"
+- options: ["Create", "Edit", "Cancel"]
+
+If "Edit" → accept modification input and redesign.
+
+### Step 5: Register Workflow
+
+Call `create_workflow`:
+
+```json
+{
+  "title": "<workflow title>",
+  "description": "<goal summary>",
+  "version": "1.0",
+  "folder_id": <selected folder id>,
+  "nodes": [...]
+}
+```
+
+### Step 6: Report Result
+
+On success:
+
+```
+✅ Workflow registered
+Name: <title> (ID: <id>)
+Steps: <n>
+Version: 1.0
+
+Type `/bk-run` to execute it now.
+```
+
+## Node Design Guidelines
+
+- 3–7 steps is ideal. Consider splitting if more than 10.
+- The first step should always be `auto_advance: false` (user provides initial context).
+- Insert a `gate` node (result review) before the final step.
+- For nodes requiring external API calls, specify `credential_id`. Create credentials first with `/bk-credential`.

package/dist/assets/skills/bk-improve/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: bk-improve
+description: BlueKiwi workflow improvement skill. Analyzes an existing workflow, creates a better version, and optionally runs it to compare results. This skill should be used when the user says "/bk-improve", "improve workflow", "make a better version", or wants to refine an existing BlueKiwi workflow.
+user_invocable: true
+---
+
+# BlueKiwi Workflow Improve
+
+Improve an existing workflow by creating a new version, then optionally execute it to compare results.
+
+## Argument Handling
+
+- `/bk-improve` → Fetch workflow list, ask user to select.
+- `/bk-improve <workflow name>` → Load that workflow directly.
+
+## Execution Steps
+
+### Step 1: Select Target Workflow
+
+If no argument, call `list_workflows` and ask via AskUserQuestion:
+
+- header: "Which workflow?"
+- "Which workflow would you like to improve?"
+- options: workflow title list (up to 4)
+
+### Step 2: Understand Improvement Direction
+
+Ask via AskUserQuestion:
+
+- header: "Improvement goal"
+- "What would you like to improve?"
+- options: ["Set more quantitative goals", "Break steps into finer detail", "Improve accuracy", "Type my own"]
+
+If "Type my own" → accept free-text improvement direction.
+
+### Step 3: Analyze the Current Workflow
+
+Display the current workflow node structure:
+
+```
+Current workflow: <title> v<version>
+━━━━━━━━━━━━━━━━━━━━━━━━━
+1. [Step name] — <instruction summary>
+2. [Step name] — <instruction summary>
+...
+━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Review each node against the improvement direction:
+
+- Vague goals → add quantitative criteria
+- Oversized steps → split them
+- Missing validation → add it
+- Unnecessary steps → remove them
+
+### Step 4: Design Improved Nodes
+
+Design the full improved node set.
+
+Show a diff of the changes:
+
+```
+Improvements:
+━━━━━━━━━━━━━━━━━━━━━━━━━
+✏️  Step 1: "Collect keywords" → "Collect top 10 keywords (by search volume)"
+➕  Step 4 added: "Quantitative validation (retry if below threshold)"
+━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ask via AskUserQuestion:
+
+- header: "Confirm"
+- "Create a new version (v<x.y>) with these improvements?"
+- options: ["Create new version", "Adjust more", "Cancel"]
+
+### Step 5: Create New Version
+
+Call `update_workflow` with `create_new_version: true`:
+
+```json
+{
+  "workflow_id": <existing id>,
+  "create_new_version": true,
+  "version": "<new version>",
+  "nodes": [<improved node array>]
+}
+```
+
+### Step 6: Offer Immediate Execution
+
+Ask via AskUserQuestion:
+
+- header: "Run now?"
+- "New version v<x.y> created. Run it now to check results?"
+- options: ["Run now", "Run later"]
+
+If "Run now" → switch to `/bk-run` flow and start a task with the new version.
+
+### Step 7: Report Result
+
+```
+✅ New version created
+Workflow: <title>
+Previous: v<old>  →  New: v<new>
+Improved steps: <n>
+```