bluekiwi 0.2.4 → 0.3.0

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

@@ -27,26 +27,84 @@ Select a registered workflow, create a task, and immediately execute the first s
 - `header` must be 12 characters or fewer.
 - `multiSelect` must be `false`.
 
-## Session Restore (Resume In-Progress Task)
+## Session Restore (Resume In-Progress or Timed-Out Task)
 
-Before starting, check for running tasks using `advance(task_id, peek=true)` if a task ID is known, or prompt the user.
+<HARD-RULE>
+Follow all steps in order before proceeding to workflow selection.
+
+### Step A — Mark zombie tasks
+
+Call `POST /api/tasks/timeout-stale` with `{"timeout_minutes": 120}`.
+This converts any `running` tasks idle for over 2 hours to `timed_out`.
+
+### Step B — Fetch existing tasks
+
+Call `list_tasks` with `status=running` and again with `status=timed_out`.
+Collect all results into a combined candidate list sorted by `updated_at` descending (most recent first).
+
+If the list is empty → skip to workflow selection.
 
-If an in-progress task is found, ask via AskUserQuestion:
+### Step C — Build the task summary
+
+For each candidate, compute age from `updated_at` to now.
+Format: `"Task #{id} — {workflow_name} (Step {current_step}/{total_steps}, {age}전)"`
+
+Example output:
+
+```
+미완료 태스크 2건이 있습니다:
+① Task #31 — 코드 리뷰 워크플로 (Step 3/6, 3시간 전) [timed_out]
+② Task #28 — 보안 점검 (Step 1/4, 30분 전) [running]
+```
 
-- header: "Resume?"
-- "Task #{id} ({workflow name}, Step {N}/{total}) is in progress. Resume or start a new workflow?"
-- options: "Resume (Recommended)" / "Start new workflow"
+### Step D — Ask what to do
 
-If resuming → call `advance(task_id, peek=true)`, read `task_context`, then switch to `/bk-next` flow.
+**Case 1: exactly 1 candidate**
+
+Ask via AskUserQuestion:
+
+- header: "미완료 태스크"
+- preview: `"Task #{id} — {workflow_name}\nStep {N}/{total} · {age}전 중단"`
+- options (pick the most appropriate 3–4):
+  - `"이어서 진행"` — resume this task
+  - `"종료하고 새로 시작"` — close this task then start fresh
+  - `"닫지 않고 새로 시작"` — leave as-is, open a new task
+  - _(only if status=running)_ `"계속 실행 중"` — another agent is handling it, do nothing
+
+**Case 2: 2 or more candidates**
+
+Ask via AskUserQuestion:
+
+- header: "미완료 태스크"
+- preview: the task summary list built above
+- options:
+  - `"가장 최근 태스크 이어서"` — resume the most recent one
+  - `"모두 종료하고 새로 시작"` — close all candidates, then start fresh
+  - `"새 태스크 시작 (기존 유지)"` — leave existing as-is, open a new task
+
+### Step E — Execute the choice
+
+**"이어서 진행" / "가장 최근 태스크 이어서"**:
+Call `advance(task_id, peek=true)`, read `task_context`, then continue with the auto-advance loop.
+
+**"종료하고 새로 시작" / "모두 종료하고 새로 시작"**:
+For each task to close, call `complete_task(task_id, summary="사용자 요청으로 종료됨")`.
+Confirm: "기존 태스크를 종료했습니다. 새 워크플로를 선택하세요." → proceed to workflow selection.
+
+**"닫지 않고 새로 시작" / "새 태스크 시작 (기존 유지)"**:
+Proceed to workflow selection without touching existing tasks.
+</HARD-RULE>
 
 ## execute_step Required Parameters
 
 <HARD-RULE>
 Always populate these parameters when calling execute_step:
 - `context_snapshot`: JSON string. Store decisions made, key findings, and hints for the next step.
-- `agent_id`: Model name in use (e.g., "claude-opus-4-6")
+- `model_id`: Current LLM model ID (e.g., "claude-opus-4-6"). Check your system prompt.
 - `user_name`: User name (omit if unknown)
 
+Note: `provider_slug` (coding tool identity) is auto-injected by the MCP server from the connection handshake. Do not send it manually.
+
 If files were created or modified, record them in the `artifacts` array:
 
 - File created: `{artifact_type: "file", title: "Design Doc", file_path: "docs/specs/design.md"}`
@@ -65,15 +123,31 @@ echo "GIT_REMOTE: $(git remote get-url origin 2>/dev/null || echo 'none')"
 echo "GIT_BRANCH: $(git branch --show-current 2>/dev/null || echo 'unknown')"
 echo "USER: $(whoami 2>/dev/null || echo 'unknown')"
 echo "OS: $(uname -s 2>/dev/null || echo 'unknown') $(uname -m 2>/dev/null)"
+# Detect CLI tool by walking up the process tree (up to 4 levels)
+_AGENT=unknown; _PID=$PPID
+for _L in 1 2 3 4; do
+  _C=$(ps -o comm= -p $_PID 2>/dev/null | tr '[:upper:]' '[:lower:]')
+  case "$_C" in
+    *claude*)   _AGENT=claude-code; break ;;
+    *gemini*)   _AGENT=gemini-cli;  break ;;
+    *codex*)    _AGENT=codex-cli;   break ;;
+    *cursor*)   _AGENT=cursor;      break ;;
+    *windsurf*) _AGENT=windsurf;    break ;;
+    *opencode*) _AGENT=opencode;    break ;;
+  esac
+  _PID=$(ps -o ppid= -p $_PID 2>/dev/null | tr -d ' ')
+  [ -z "$_PID" ] || [ "$_PID" = "0" ] || [ "$_PID" = "1" ] && break
+done
+echo "AGENT: $_AGENT"
 ```
 
 Build a JSON object:
 
 ```json
 {
+  "agent": "claude-code",
   "project_dir": "/Users/dante/workspace/project",
   "user_name": "dante",
-  "agent": "claude-code",
   "model_id": "claude-opus-4-6",
   "git_remote": "git@github.com:user/repo.git",
   "git_branch": "main",
@@ -82,7 +156,7 @@ Build a JSON object:
 }
 ```
 
-- `agent`: always "claude-code" when running in Claude Code
+- `agent`: detected CLI tool name (from AGENT output above)
 - `model_id`: current model ID (check system prompt)
 - `started_at`: current UTC time
   </HARD-RULE>
@@ -104,17 +178,37 @@ Record only results (URL, status code, response summary).
 
 Call `list_workflows` to retrieve the list.
 
+**No workflows exist**: Ask via AskUserQuestion:
+
+- header: "No workflows"
+- "No workflows found. Would you like to create one now?"
+- options: "Create new workflow" / "Cancel"
+
+If "Create new workflow" → immediately invoke the `bk-design` skill. Pass the user's original argument (if any) as the goal so `bk-design` can pre-fill the design step. After `bk-design` completes and the workflow is registered, return here and proceed with Step 2 using the newly created workflow.
+
 **Single workflow**: Skip the selection UI, just confirm:
 
 - "Start the '{title}' workflow?" (AskUserQuestion: "Start" / "Cancel")
 
 **Multiple workflows**: Show selection via AskUserQuestion.
 
-### 2. Create Task
+If the user selects "Create new workflow" from the selection UI → invoke `bk-design`, then continue as above.
+
+### 2. Create Task + Open Monitoring Page
 
 Call `start_workflow`. Pass any argument as `context`.
 
-### 3. Execute First Step + auto_advance Loop
+<HARD-RULE>
+After `start_workflow` returns the task_id, immediately open the task monitoring page in the user's browser:
+
+```bash
+open "${BLUEKIWI_URL:-http://localhost:3100}/tasks/${TASK_ID}"
+```
+
+Use `open` on macOS, `xdg-open` on Linux. Derive `BLUEKIWI_URL` from the MCP connection or default to `http://localhost:3100`.
+</HARD-RULE>
+
+### 3. Execute First Step + Auto-Advance Loop
 
 Read the first step's instruction as an **internal directive and execute immediately**.
 
@@ -127,19 +221,188 @@ Starting: {workflow title} ({n} steps)
 ━━━━━━━━━━━━━━━━━━━━━━━━━
 **1** → 2 → 3 → 4 → 5 → 6 → 7
 ━━━━━━━━━━━━━━━━━━━━━━━━━
+📺 Live: ${BLUEKIWI_URL}/tasks/${TASK_ID}
+━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**auto_advance loop**: If the next step has `auto_advance: true`, continue executing without pausing.
+**Auto-advance loop**: If execute_step returns no `next_action`, continue executing the next step without pausing.
 
 <HARD-RULE>
-After executing an auto_advance=true step, always proceed to the next step automatically.
+After executing a step with no next_action, always proceed to the next step automatically.
 Show a brief inline update: "✅ [{title}] done → continuing to next step..."
-Repeat the loop until reaching an auto_advance=false step.
+Repeat the loop until reaching a gate step or a hitl=true action step.
 </HARD-RULE>
 
 ### 4. When Pausing
 
-- **HITL** (execute_step returned `next_action: "wait_for_human_approval"`):
-  Call `request_approval`, show "⏸ Waiting for approval ��� use /bk-approve when ready.", stop.
-- After completing an action step (auto_advance=false, no HITL): "Type `/bk-next` to proceed."
-- After showing a gate question: Wait for user response. Do not show `/bk-next` hint.
+Check the `next_action` field in the `execute_step` response and handle accordingly:
+
+#### HITL (next_action: "wait_for_human_approval")
+
+Call `request_approval`, then immediately show the HITL approval AskUserQuestion (inline HITL approval). Do NOT stop and tell the user to type `/bk-approve`.
+
+#### Gate step (no next_action, node_type=gate)
+
+<HARD-RULE>
+Write all VS content text (titles, descriptions, option labels, button text)
+in the user's language. The frame UI (Submit button, status) is auto-localized,
+but agent-authored content must match the user's locale.
+</HARD-RULE>
+
+- If `visual_selection: true`:
+  1. Compose a VS content **fragment** using `bk-*` component classes. Write **only the inner HTML** - do not include `<html>`, `<head>`, or `<body>` tags. The frame (CSS, JS, submit button) is injected automatically by the web UI.
+
+     **Component quick reference:**
+     - Selection: `bk-options` (A/B/C cards, single), `bk-cards` (visual cards, single), `bk-checklist` (multi-select), `bk-code-compare` (code blocks, single)
+     - Input: `bk-slider` (numeric range), `bk-ranking` (drag reorder), `bk-matrix` (2x2 drag placement)
+     - Display: `bk-split`, `bk-pros-cons`, `bk-mockup`, `bk-timeline`
+     - Layout: `h2`, `.bk-subtitle`, `.bk-section`, `.bk-label`
+
+     Every selection/input element needs a `data-value` attribute. Example fragment:
+
+     ```html
+     <h2>Choose an approach</h2>
+     <p class="bk-subtitle">
+       Select the architecture that best fits your needs
+     </p>
+     <div class="bk-options">
+       <div class="bk-option" data-value="monolith" data-recommended>
+         <div class="bk-option-letter">A</div>
+         <div class="bk-option-body">
+           <h3>Monolith</h3>
+           <p>Simple deployment</p>
+         </div>
+       </div>
+       <div class="bk-option" data-value="microservices">
+         <div class="bk-option-letter">B</div>
+         <div class="bk-option-body">
+           <h3>Microservices</h3>
+           <p>Independent scaling</p>
+         </div>
+       </div>
+     </div>
+     ```
+
+  2. Call `set_visual_html(task_id, node_id, html)` with the fragment.
+  3. Open the VS deep link so the user sees the selection UI immediately:
+     ```bash
+     open "${BLUEKIWI_URL:-http://localhost:3100}/tasks/${TASK_ID}?step=${STEP_ORDER}&vs=true"
+     ```
+  4. Poll `get_web_response(task_id)` every 3-5 seconds until a response arrives (max 120 seconds).
+  5. The response is a **JSON object** (not a plain string). Parse it to read the user's choices:
+
+     ```json
+     {
+       "selections": ["monolith"],
+       "values": { "budget": 70 },
+       "ranking": ["security", "ux"]
+     }
+     ```
+
+     - `selections`: chosen option values (from bk-options, bk-cards, bk-checklist, bk-code-compare)
+     - `values`: numeric inputs (from bk-slider, keyed by data-name)
+     - `ranking`: ordered list (from bk-ranking)
+     - `matrix`: placement coordinates (from bk-matrix)
+       Only populated fields appear.
+
+  6. Use the parsed response to form the gate answer and call `advance`.
+
+- If `visual_selection: false` → present the gate question to the user via AskUserQuestion. Use the response as gate answer, call `execute_step` with the answer, then `advance`.
+
+#### Attachments
+
+<HARD-RULE>
+When `advance` returns `node.attachments`:
+1. Review the list (filename, mime_type, size_bytes)
+2. Call `get_attachment(workflow_id, node_id, attachment_id)` for each text file the instruction references
+3. Use downloaded content as context when executing the instruction
+4. For binary files, note their existence but do not download unless explicitly required
+</HARD-RULE>
+
+#### Loop (next_action: "loop_back")
+
+<HARD-RULE>
+Loop nodes repeat until a termination condition is met. The instruction contains the termination condition.
+
+**Execution flow:**
+
+1. Read the instruction and execute one iteration (e.g., ask one clarifying question).
+2. Present the result/question to the user via AskUserQuestion.
+3. Based on user response, decide: is the termination condition met?
+   - **NOT met** → call `execute_step(loop_continue=true)` → server creates a new pending log on the same node → re-execute the loop step (go back to step 1)
+   - **Met** → call `execute_step(loop_continue=false)` → loop ends → call `advance` to move to next step
+
+**Example — "Clarifying Questions" loop (loop_back_to=self):**
+
+```
+Iteration 1: "Who is the primary user of this feature?" → user answers → purpose clear, constraints unclear → loop_continue=true
+Iteration 2: "Are there tech stack limitations?" → user answers → constraints clear, success criteria unclear → loop_continue=true
+Iteration 3: "What defines completion?" → user answers → all items clear → loop_continue=false → advance
+```
+
+**Example — "Design Section Presentation" loop:**
+
+```
+Iteration 1: Present architecture section → user "looks good" → more sections remain → loop_continue=true
+Iteration 2: Present data flow section → user "needs revision" → revise and re-present → loop_continue=true
+Iteration 3: Present final section → user approves → all sections done → loop_continue=false → advance
+```
+
+</HARD-RULE>
+
+#### Loop + VS History Pattern
+
+When a loop node uses `visual_selection: true`, each iteration presents a VS screen and collects a response. Use `get_web_response(task_id, node_id)` to access all previous iteration responses for that node:
+
+```json
+{
+  "task_id": 19,
+  "node_id": 109,
+  "history": [
+    {
+      "iteration": 1,
+      "web_response": { "selections": ["a"] },
+      "created_at": "..."
+    },
+    {
+      "iteration": 2,
+      "web_response": { "selections": ["b"], "values": { "confidence": 80 } },
+      "created_at": "..."
+    }
+  ]
+}
+```
+
+Use the history to adapt subsequent VS screens - for example, pre-selecting the user's previous choice, adjusting slider defaults based on past values, or skipping already-confirmed items.
+
+## Graceful Interruption (중단 처리)
+
+<HARD-RULE>
+Whenever the user requests a stop mid-workflow — phrases like "stop", "pause", "cancel", "잠깐", "중단", "그만", "멈춰", or presses Ctrl+C — you MUST ask before exiting:
+
+Ask via AskUserQuestion:
+
+- header: "작업 중단"
+- "현재 Step {N}에서 중단합니다. 어떻게 처리할까요?"
+- options:
+  - "일시 중지 (나중에 이어서)" — leave task as `running`; it will auto-timeout after 2 hours of inactivity, and can be resumed next session
+  - "태스크 종료 (완전히 닫기)" — call `complete_task(task_id, summary="사용자 요청으로 중단됨")` to mark the task finished
+  - "계속 진행" — dismiss and continue the current step
+
+If "일시 중지":
+
+- Save the current progress to `context_snapshot` via `execute_step` (mark output as "작업이 일시 중지되었습니다. 다음 세션에서 이어서 진행 가능합니다.")
+- Remind the user: "Task #{id}은 Step {N}에서 일시 중지되었습니다. 다음에 `/bk-start`를 실행하면 이어서 진행할 수 있습니다."
+
+If "태스크 종료":
+
+- Call `complete_task(task_id, summary="사용자 요청으로 중단됨. 마지막 완료 스텝: {N}")`.
+- Remind the user: "태스크가 종료되었습니다. 처음부터 다시 시작하려면 `/bk-start`를 실행하세요."
+
+**When not to prompt**: If ALL steps are already completed and `complete_task` is about to be called, skip this dialog — the workflow is naturally finishing.
+</HARD-RULE>
+
+## Feedback Survey (before calling complete_task)
+
+When the workflow finishes, run the feedback survey flow.
+Follow the sequence: `save_feedback` → `complete_task` → suggest improvements.

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

@@ -8,27 +8,57 @@ user_invocable: true
 
 View the progress of active and completed tasks.
 
+## Argument Handling
+
+- `/bk-status` → Show all running tasks. If none, show recent completed tasks.
+- `/bk-status <task_id>` → Show detailed step-by-step log for that task.
+- `/bk-status running` → Show only running tasks.
+- `/bk-status completed` → Show only completed tasks.
+
 ## Execution Steps
 
 ### 1. Fetch Tasks
 
-Call `advance` with `peek: true` on any known active task, or check the server for running tasks.
+Call `list_tasks` with optional filters:
+
+- No argument: `list_tasks()` (all tasks) or `list_tasks(status="running")`
+- With status filter: `list_tasks(status="running")` or `list_tasks(status="completed")`
+- With task_id: `advance(task_id=<id>, peek=true)` for detailed view
 
-### 2. Display Results
+### 2. Display Task List
 
 ```
 BlueKiwi Task Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━
   #1  [completed] Feature Brainstorm   8/8 steps   2026-04-07
   #2  [running]   PR Security Review   2/4 steps   2026-04-07  ← active
+  #3  [running]   DB Migration Plan    5/7 steps   2026-04-08  ← active
 ━━━━━━━━━━━━━━━━━━━━━━━━━
+Active: 2 tasks
 ```
 
 ### 3. Detailed View
 
-If a task number is given as an argument (`/bk-status 2`), show the step-by-step log for that task.
+If a task number is given, call `advance(task_id=<id>, peek=true)` and show the step-by-step log:
+
+```
+Task #2: PR Security Review (running)
+━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅ 1. Code Analysis          completed  12s
+  ✅ 2. Dependency Check        completed  8s
+  ⏸ 3. Security Review         pending    ← current (gate)
+  ○  4. Report Generation       —
+━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 4. Offer Actions
+
+After displaying, ask via AskUserQuestion:
+
+- header: "Actions"
+- options: ["Resume active task (/bk-start)", "View detailed task", "Done"]
 
 ## Notes
 
-- Web UI: http://localhost:3000/tasks
-- Real-time monitoring: Requires WebSocket Relay (`npm run ws`)
+- `list_tasks` respects RBAC — only tasks on workflows the user can read are returned.
+- For real-time monitoring, use the web UI: http://localhost:3000/tasks

package/dist/commands/dev-link.js

@@ -11,7 +11,7 @@ export async function devLinkCommand() {
     for (const adapter of detectInstalledAdapters()) {
         const target = adapter.getSkillsDir();
         mkdirSync(target, { recursive: true });
-        for (const skill of ["bk-start", "bk-next", "bk-status", "bk-rewind"]) {
+        for (const skill of ["bk-start", "bk-status", "bk-rewind"]) {
             const link = join(target, skill);
             if (existsSync(link)) {
                 rmSync(link, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluekiwi",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "BlueKiwi CLI — install MCP client and skills into your agent runtime",
   "license": "MIT",
   "repository": {

package/dist/assets/mcp/api-client.d.ts

@@ -1,6 +0,0 @@
-export declare class BlueKiwiClient {
-  private baseUrl;
-  private apiKey;
-  constructor(baseUrl: string, apiKey: string);
-  request<T>(method: string, path: string, body?: unknown): Promise<T>;
-}

package/dist/assets/mcp/api-client.js

@@ -1,67 +0,0 @@
-import {
-  BlueKiwiAuthError,
-  BlueKiwiApiError,
-  BlueKiwiNetworkError,
-} from "./errors.js";
-const RETRY_DELAYS_MS = [100, 500, 2000];
-export class BlueKiwiClient {
-  baseUrl;
-  apiKey;
-  constructor(baseUrl, apiKey) {
-    this.baseUrl = baseUrl;
-    this.apiKey = apiKey;
-    if (!baseUrl) throw new Error("BlueKiwiClient: baseUrl is required");
-    if (!apiKey) throw new Error("BlueKiwiClient: apiKey is required");
-  }
-  async request(method, path, body) {
-    const url = `${this.baseUrl.replace(/\/$/, "")}${path}`;
-    const init = {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
-    };
-    let lastError;
-    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
-      try {
-        const res = await fetch(url, init);
-        if (res.status === 401) {
-          throw new BlueKiwiAuthError();
-        }
-        if (!res.ok) {
-          const text = await res.text().catch(() => "");
-          if (res.status >= 500 && attempt < RETRY_DELAYS_MS.length) {
-            lastError = new BlueKiwiApiError(res.status, text);
-            await sleep(RETRY_DELAYS_MS[attempt]);
-            continue;
-          }
-          throw new BlueKiwiApiError(res.status, text);
-        }
-        const text = await res.text();
-        return text ? JSON.parse(text) : null;
-      } catch (err) {
-        if (
-          err instanceof BlueKiwiAuthError ||
-          err instanceof BlueKiwiApiError
-        ) {
-          throw err;
-        }
-        lastError = err;
-        if (attempt < RETRY_DELAYS_MS.length) {
-          await sleep(RETRY_DELAYS_MS[attempt]);
-          continue;
-        }
-        throw new BlueKiwiNetworkError(
-          `Failed to reach ${url} after ${RETRY_DELAYS_MS.length + 1} attempts`,
-          err,
-        );
-      }
-    }
-    throw new BlueKiwiNetworkError("Unreachable", lastError);
-  }
-}
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}

package/dist/assets/mcp/errors.d.ts

@@ -1,12 +0,0 @@
-export declare class BlueKiwiAuthError extends Error {
-  constructor(message?: string);
-}
-export declare class BlueKiwiApiError extends Error {
-  readonly status: number;
-  readonly body: string;
-  constructor(status: number, body: string);
-}
-export declare class BlueKiwiNetworkError extends Error {
-  readonly cause?: unknown | undefined;
-  constructor(message: string, cause?: unknown | undefined);
-}

package/dist/assets/mcp/errors.js

@@ -1,24 +0,0 @@
-export class BlueKiwiAuthError extends Error {
-  constructor(message = "Invalid or expired API key") {
-    super(message);
-    this.name = "BlueKiwiAuthError";
-  }
-}
-export class BlueKiwiApiError extends Error {
-  status;
-  body;
-  constructor(status, body) {
-    super(`BlueKiwi API error ${status}: ${body}`);
-    this.status = status;
-    this.body = body;
-    this.name = "BlueKiwiApiError";
-  }
-}
-export class BlueKiwiNetworkError extends Error {
-  cause;
-  constructor(message, cause) {
-    super(message);
-    this.cause = cause;
-    this.name = "BlueKiwiNetworkError";
-  }
-}

package/dist/assets/mcp/server.d.ts

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