assistme 0.2.9 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistme",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "AssistMe CLI Agent - AI-powered assistant that controls your real browser",
   "type": "module",
   "main": "dist/index.js",

package/src/agent/mcp-servers.ts

@@ -9,7 +9,7 @@ import { getLimiterForTool } from "../utils/rate-limiter.js";
 import { log } from "../utils/logger.js";
 import type { MemoryManager, MemoryCategory } from "./memory.js";
 import type { SkillManager } from "./skills.js";
-import { substituteArguments, preprocessDynamicContext } from "./skills.js";
+import { substituteArguments, preprocessDynamicContext, validateSkillName } from "./skills.js";
 import { emitEvent, setActionRequest, pollActionResponse } from "../db/supabase.js";
 import { callMcpHandler } from "../db/api-client.js";
 import { JobRunner } from "./job-runner.js";
@@ -223,6 +223,17 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
           emoji: z.string().optional().describe("Single emoji representing this skill"),
         },
         async (args) => {
+          // Validate skill name format
+          const nameError = validateSkillName(args.name);
+          if (nameError) {
+            return {
+              content: [{
+                type: "text",
+                text: `Invalid skill name: ${nameError}. Use lowercase kebab-case like "flight-booking".`,
+              }],
+            };
+          }
+
           // Check for duplicates in user's collection
           const existing = skillManager.findSimilar(args.name);
           if (existing) {
@@ -442,12 +453,12 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
           }
 
           response += `**Your task:** Analyze this job description and decompose it into 4-10 automatable skills.\n\n`;
-          response += `**IMPORTANT — You MUST use request_user_confirmation before creating skills:**\n`;
+          response += `**IMPORTANT — You MUST use ask_user before creating skills:**\n`;
           response += `1. Analyze the job and draft a list of proposed skills (name, emoji, one-line description for each).\n`;
-          response += `2. Call \`request_user_confirmation\` with the formatted skill list as "message" and these options:\n`;
+          response += `2. Call \`ask_user\` with the formatted skill list as "question" and these options:\n`;
           response += `   - options: [{label: "Approve All", action_key: "approve_all", description: "Create all proposed skills"}, {label: "Cancel", action_key: "cancel", description: "Do not create any skills"}]\n`;
           response += `3. WAIT for the response. If action_key is "approve_all", create all skills using \`skill_create\`. If "cancel", stop.\n`;
-          response += `4. Do NOT ask for confirmation in text. Do NOT create skills without calling request_user_confirmation first.\n\n`;
+          response += `4. Do NOT ask for confirmation in text. Do NOT create skills without calling ask_user first.\n\n`;
           response += `For each skill, call \`skill_create\` with:\n`;
           response += `- name: kebab-case name (e.g. "slack-message-check")\n`;
           response += `- description: one-line description\n`;
@@ -605,59 +616,63 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
         }
       ),
 
-      // ── User Confirmation Tool ─────────────────────────────────
+      // ── User Interaction Tool ───────────────────────────────────
 
       tool(
-        "request_user_confirmation",
-        "Pause and ask the user for approval or input via the web UI. " +
-          "Returns the user's chosen action_key. Use this BEFORE creating skills, making irreversible changes, etc. " +
-          "The agent will block until the user responds or the timeout expires.",
+        "ask_user",
+        "Ask the user a question via the web UI and wait for their response. " +
+          "Shows a message with optional predefined option buttons PLUS a free-text input field — " +
+          "the user can either click a suggested option or type a custom answer. " +
+          "ALWAYS provide options when you can suggest likely answers. " +
+          "Do NOT use this for information you can discover yourself (git remote, file contents, etc.).",
         {
-          message: z.string().describe("What to show the user (supports markdown)"),
+          question: z.string().describe("The question to ask (supports markdown). Be specific about what you need and why."),
           options: z.array(z.object({
             label: z.string().describe("Button label shown to user"),
             action_key: z.string().describe("Machine-readable key returned when selected"),
             description: z.string().optional().describe("Tooltip/description for this option"),
-          })).describe("Buttons/options to show the user"),
+          })).optional().describe("Suggested options shown as buttons. The user can always type a custom answer instead."),
+          placeholder: z.string().optional().describe("Placeholder text for the free-text input field"),
           timeout_seconds: z.number().optional().describe("How long to wait for response (default: 300)"),
         },
         async (args) => {
-          const actionId = `action_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+          const actionId = `ask_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
           const timeout = (args.timeout_seconds || 300) * 1000;
 
           const actionData = {
             id: actionId,
-            type: "confirmation",
-            message: args.message,
-            options: args.options,
+            type: "ask_user",
+            message: args.question,
+            options: args.options || [],
+            placeholder: args.placeholder || "",
             created_at: new Date().toISOString(),
           };
 
           try {
-            // Store action request in message metadata via RPC — UI reads this
             await setActionRequest(taskId, actionData);
-            log.info(`Action request ${actionId} stored in metadata, waiting for user response...`);
+            log.info(`Ask user ${actionId}: "${args.question.slice(0, 80)}..."`);
 
-            // Also emit event for real-time notification (best-effort)
             emitEvent(taskId, "user_action_request", actionData).catch(() => {});
 
-            // Poll for response
             const startTime = Date.now();
             const pollInterval = 2000;
 
             while (Date.now() - startTime < timeout) {
               const response = await pollActionResponse(taskId);
-              if (response) {
-                const actionKey = (response.action_key || response.action || "") as string;
-                const label = (response.label || actionKey) as string;
-                log.info(`User responded: ${label} (${actionKey})`);
+              if (response && (!response.action_id || response.action_id === actionId)) {
+                // Response can be either an option click or free-text input
+                const actionKey = (response.action_key || "") as string;
+                const text = (response.text || "") as string;
+                const label = (response.label || actionKey || text) as string;
+                log.info(`User responded: "${label}"`);
                 return {
                   content: [{
                     type: "text",
                     text: JSON.stringify({
                       status: "responded",
-                      action_key: actionKey,
+                      action_key: actionKey || "custom_input",
                       label,
+                      text: text || label,
                     }),
                   }],
                 };
@@ -666,7 +681,7 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
               await new Promise((resolve) => setTimeout(resolve, pollInterval));
             }
 
-            log.warn(`Action request ${actionId} timed out after ${args.timeout_seconds || 300}s`);
+            log.warn(`Ask user ${actionId} timed out after ${args.timeout_seconds || 300}s`);
             return {
               content: [{
                 type: "text",
@@ -677,11 +692,11 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
               }],
             };
           } catch (err) {
-            log.error(`request_user_confirmation failed: ${err}`);
+            log.error(`ask_user failed: ${err}`);
             return {
               content: [{
                 type: "text",
-                text: `Failed to request user confirmation: ${err instanceof Error ? err.message : err}`,
+                text: `Failed to ask user: ${err instanceof Error ? err.message : err}`,
               }],
             };
           }

package/src/agent/processor.ts

@@ -21,6 +21,7 @@ import { getBrowser } from "../tools/browser.js";
 import { MemoryManager } from "./memory.js";
 import { SkillManager } from "./skills.js";
 import { type ToolCallRecord } from "./skill-extractor.js";
+import { evaluateAndMaybeCreateSkill } from "./skill-evaluator.js";
 import { withRetry } from "../utils/retry.js";
 import {
   createBrowserMcpServer,
@@ -58,17 +59,29 @@ Available capabilities:
    - PROACTIVELY use memory_store during tasks when you discover user preferences, habits, or important context
    - Before completing a task, consider if anything learned should be remembered for future conversations
 
-4. SKILL PLANNING (pre-task):
-   - Before executing a complex task, analyze if it matches an existing skill (use skill_invoke)
-   - If no matching skill exists, consider whether this task represents a reusable workflow
-   - To create a new skill: use skill_create to save a draft, then ASK the user if they want to add it
-   - If the user approves, use skill_add to add it to their collection, then proceed with the task
-   - If a skill's instructions could be improved based on your experience, use skill_improve
-   - Use skill_search to find relevant skills when the task doesn't obviously match the listed skills
+4. SKILL-AWARE EXECUTION (CRITICAL — follow this for EVERY task):
+   Step A — Search: Before executing ANY task, check if an existing skill matches (use skill_invoke or skill_search).
+   Step B — If skill found: load it with skill_invoke and follow its instructions precisely. If the instructions are incomplete or wrong, adapt and improve as you go — note what changed.
+   Step C — If NO skill found: BEFORE executing, draft a skill plan following the Agent Skills format:
+     Skill Draft: [kebab-case-name]
+     Description: [what this skill does and when to use it]
+     Steps:
+     1. [first step]
+     2. [second step]
+     ...
+     The draft should be a reusable workflow, not specific to this one request. Use generic placeholders where the user provided specific values.
+   Step D — Execute: Follow the skill draft (or loaded skill) step by step. Refine the draft as you discover better approaches, edge cases, or missing steps.
+   Step E — After execution: The system will automatically evaluate whether to save the skill. You do NOT need to call skill_create manually.
+
+   Agent Skills format reference (agentskills.io):
+   - name: 1-64 chars, lowercase kebab-case (a-z, 0-9, hyphens), no leading/trailing/consecutive hyphens
+   - description: 1-1024 chars, describe what the skill does AND when to use it, include keywords for discoverability
+   - body: markdown step-by-step instructions, examples, edge cases. Keep under 500 lines.
+   - Progressive disclosure: metadata (~100 tokens) → instructions (<5000 tokens) → references (on demand)
 
 5. JOB AUTOMATION:
    - When the user describes their job/role/daily work, use skill_generate to decompose it into automatable skills
-   - ALWAYS use request_user_confirmation to get user approval before creating skills — never create skills without approval
+   - ALWAYS use ask_user to get user approval before creating skills — never create skills without approval
    - Use job_run to start a job — it gives you the job's goal and available skills as capabilities
    - When running a job, be AGENTIC: decide dynamically what to do based on what you discover
    - Do NOT follow a fixed sequence — if checking Slack reveals a task that needs GitHub, go do GitHub immediately
@@ -101,6 +114,15 @@ Guidelines:
 - Summarize results clearly at the end
 - When you learn something about the user (preferences, habits), use memory_store to remember it
 
+CRITICAL — Ask before you guess:
+- Before executing a task, verify you have all required information. If anything is ambiguous or missing, use ask_user to ask.
+- First try to resolve unknowns yourself: check memories, read workspace files (e.g. git remote, config files), or infer from conversation history.
+- If you still lack a critical piece of information after self-resolution, ASK the user via ask_user. Do NOT guess, assume defaults, or proceed with incomplete information.
+- When asking, provide suggested options as buttons whenever possible — the user can always type a custom answer instead.
+- Examples of when to ask: which account/repo/project to target, what format the user wants, which of multiple options to choose, credentials or URLs that cannot be inferred.
+- Keep questions specific and actionable. Explain what you already know and what exactly you need.
+- After receiving the answer, store it with memory_store if it is likely to be useful in future conversations.
+
 Workspace path: {workspace_path}`;
 
 const MAX_HISTORY_ENTRIES = 10;
@@ -132,6 +154,22 @@ export class TaskProcessor {
     this.sessionId = sessionId;
   }
 
+  /**
+   * Post-task: resume the same Agent SDK session to evaluate whether
+   * to create/update a skill. The agent already has full context from
+   * the task it just completed — no need to re-describe anything.
+   */
+  private async evaluateSkillPostTask(
+    agentSessionId: string,
+    model: string
+  ): Promise<void> {
+    await evaluateAndMaybeCreateSkill({
+      sessionId: agentSessionId,
+      skillManager: this.skillManager,
+      model,
+    });
+  }
+
   async processTask(task: AgentTask): Promise<void> {
     const config = getConfig();
     resetEventSequence();
@@ -148,6 +186,7 @@ export class TaskProcessor {
     let finalResponse = "";
     const toolCallRecords: ToolCallRecord[] = [];
     let tokenUsage: Record<string, number> | undefined;
+    let agentSessionId: string | undefined;
 
     try {
       // Task is already claimed atomically by pollAndClaimTask in session.ts
@@ -169,7 +208,8 @@ export class TaskProcessor {
       }
 
       // Inject lightweight skill descriptions (full content loaded on-demand via skill_invoke)
-      const skillPrompt = this.skillManager.buildSkillDescriptions();
+      // Pass task prompt so relevant skills are prioritized to the top
+      const skillPrompt = this.skillManager.buildSkillDescriptions(task.prompt);
       if (skillPrompt) {
         systemPrompt += skillPrompt;
       }
@@ -237,8 +277,8 @@ export class TaskProcessor {
         "mcp__assistme-agent__skill_browse",
         "mcp__assistme-agent__skill_add",
         "mcp__assistme-agent__skill_publish",
-        // User confirmation
-        "mcp__assistme-agent__request_user_confirmation",
+        // User interaction
+        "mcp__assistme-agent__ask_user",
         // Job automation tools
         "mcp__assistme-agent__job_run",
         "mcp__assistme-agent__job_schedule",
@@ -272,7 +312,7 @@ export class TaskProcessor {
           "assistme-agent": agentToolsServer,
         },
         hooks: eventHooks,
-        persistSession: false,
+        persistSession: true,
         abortController,
       };
 
@@ -344,7 +384,10 @@ export class TaskProcessor {
             }
 
             default:
-              // system, user, tool_progress, etc. — log but no action needed
+              // Capture session ID from init message for post-task session resume
+              if (message.type === "system" && "subtype" in message && (message as Record<string, unknown>).subtype === "init") {
+                agentSessionId = (message as Record<string, unknown>).session_id as string;
+              }
               log.debug(`SDK message type: ${message.type}`);
               break;
           }
@@ -371,9 +414,11 @@ export class TaskProcessor {
       }
       this.historyCache.set(task.conversation_id, convHistory);
 
-      // Note: Memory extraction and skill creation are handled by the agent itself
-      // during task execution via memory_store and skill_create tools.
-      // No separate LLM API calls needed — the agent SDK handles everything.
+      // Post-task: resume the same session to evaluate skill creation (fire-and-forget)
+      if (agentSessionId) {
+        this.evaluateSkillPostTask(agentSessionId, config.model)
+          .catch((err) => log.debug(`Post-task skill evaluation skipped: ${err}`));
+      }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       log.error(`Task failed: ${errorMsg}`);

package/src/agent/skill-evaluator.ts

@@ -0,0 +1,258 @@
+import {
+  query,
+  type SDKAssistantMessage,
+  type SDKResultMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import { log } from "../utils/logger.js";
+import type { SkillManager } from "./skills.js";
+import { validateSkillName, normalizeSkillName } from "./skills.js";
+
+// ── Types ───────────────────────────────────────────────────────────
+
+interface SkillDecision {
+  action: "create" | "update" | "skip";
+  // For "create"
+  name?: string;
+  description?: string;
+  instructions?: string;
+  emoji?: string;
+  keywords?: string[];
+  // For "update"
+  existing_skill_name?: string;
+  improved_instructions?: string;
+  improved_description?: string;
+  // Always present
+  reason: string;
+}
+
+// ── Agent Skills format spec (agentskills.io) ───────────────────────
+
+const SKILL_EVALUATION_PROMPT = `You just completed a task. Now evaluate whether it should be saved as a reusable Agent Skill.
+
+## Agent Skills Format (agentskills.io)
+
+A skill follows the SKILL.md format:
+- name: 1-64 chars, lowercase kebab-case (a-z, 0-9, hyphens), no leading/trailing/consecutive hyphens
+- description: 1-1024 chars, describe WHAT it does AND WHEN to use it, include searchable keywords
+- body: markdown step-by-step instructions, examples, edge cases. Keep under 500 lines, <5000 tokens.
+- Use generic placeholders (e.g. {url}, {query}, {product_name}) instead of specific values
+- Instructions should be a REUSABLE workflow, not a transcript of what just happened
+- Include error handling steps and tool references (browser_navigate, browser_read_page, Bash, Read, etc.)
+
+## Your Decision
+
+Respond with ONLY a JSON object (no markdown, no explanation outside the JSON). Choose one action:
+
+1. **"create"** — The task is a reusable workflow worth saving.
+   Include: name, description, instructions (full SKILL.md body), emoji, keywords (3-5, include Chinese if task was in Chinese)
+
+2. **"update"** — An existing skill should be improved based on what you just learned.
+   Include: existing_skill_name, improved_instructions (full updated body), improved_description (if changed)
+
+3. **"skip"** — Not worth capturing (simple Q&A, one-off, too vague, already fully covered by existing skill).
+
+Always include "reason" explaining your decision.
+
+Use your judgment — no rigid rules. Consider: Is this repeatable? Can it be generalized? Would it save time next time?`;
+
+// ── Evaluator ───────────────────────────────────────────────────────
+
+/**
+ * Post-task skill evaluator using Agent SDK session resume.
+ *
+ * Resumes the same session that just completed the task, so the agent
+ * has full context of what happened. No need to re-describe the task,
+ * tool calls, or results — it already knows everything.
+ */
+export async function evaluateAndMaybeCreateSkill(opts: {
+  sessionId: string;
+  skillManager: SkillManager;
+  model?: string;
+}): Promise<void> {
+  const { sessionId, skillManager, model } = opts;
+
+  if (!sessionId) {
+    log.debug("Skill evaluation skipped: no session ID to resume");
+    return;
+  }
+
+  // Build existing skills context so the agent knows what already exists
+  const existingSkills = skillManager.getAll();
+  const existingList = existingSkills.length > 0
+    ? existingSkills.map((s) => `- ${s.name}: ${s.description}`).join("\n")
+    : "(no existing skills)";
+
+  const prompt = `${SKILL_EVALUATION_PROMPT}
+
+## Existing Skills (do NOT duplicate these)
+${existingList}
+
+Respond with a JSON object now.`;
+
+  try {
+    let responseText = "";
+
+    for await (const message of query({
+      prompt,
+      options: {
+        resume: sessionId,
+        model,
+        maxTurns: 1,
+        allowedTools: [],
+      },
+    })) {
+      if (message.type === "assistant") {
+        const assistantMsg = message as SDKAssistantMessage;
+        for (const block of assistantMsg.message.content) {
+          if (block.type === "text") {
+            responseText += block.text;
+          }
+        }
+      } else if (message.type === "result") {
+        const resultMsg = message as SDKResultMessage;
+        if (resultMsg.subtype === "success" && "total_cost_usd" in resultMsg) {
+          log.debug(`Skill evaluation cost: $${(resultMsg as { total_cost_usd: number }).total_cost_usd.toFixed(4)}`);
+        }
+      }
+    }
+
+    // Parse the decision — try the full text first, then extract JSON
+    const decision = parseJsonResponse(responseText);
+    if (!decision) {
+      log.debug("Skill evaluation: no valid JSON in response");
+      return;
+    }
+
+    if (!["create", "update", "skip"].includes(decision.action)) {
+      log.debug("Skill evaluation: invalid action");
+      return;
+    }
+
+    // Execute the decision
+    await executeSkillDecision(decision, skillManager);
+  } catch (err) {
+    log.debug(`Skill evaluation error: ${err}`);
+  }
+}
+
+/**
+ * Execute the skill decision: create a new skill or update an existing one.
+ */
+async function executeSkillDecision(
+  decision: SkillDecision,
+  skillManager: SkillManager
+): Promise<void> {
+  switch (decision.action) {
+    case "create": {
+      if (!decision.name || !decision.instructions) {
+        log.debug("Skill create skipped: missing name or instructions");
+        return;
+      }
+
+      // Normalize name to valid kebab-case (model may return invalid format)
+      let skillName = decision.name;
+      if (validateSkillName(skillName)) {
+        skillName = normalizeSkillName(skillName);
+        if (!skillName || validateSkillName(skillName)) {
+          log.debug(`Skill create skipped: name "${decision.name}" cannot be normalized`);
+          return;
+        }
+        log.debug(`Normalized skill name: "${decision.name}" → "${skillName}"`);
+      }
+
+      // Check for duplicates
+      const existing = skillManager.findSimilar(skillName);
+      if (existing) {
+        log.debug(`Skill create skipped: similar skill "${existing.name}" exists`);
+        return;
+      }
+
+      const result = await skillManager.create(
+        skillName,
+        decision.description || "",
+        decision.instructions,
+        {
+          source: "auto_extracted",
+          emoji: decision.emoji,
+          keywords: decision.keywords,
+        }
+      );
+
+      if (result) {
+        // syncToAgentSkills is handled by skill_create flow; only sync here
+        // with sourceSkillId linkage since create() doesn't set it.
+        await skillManager.syncToAgentSkills(
+          skillName,
+          decision.description || "",
+          decision.instructions,
+          "1.0.0",
+          {
+            source: "auto_extracted",
+            emoji: decision.emoji,
+            keywords: decision.keywords,
+            sourceSkillId: result.id,
+          }
+        );
+        log.info(`Auto-created skill "${skillName}": ${decision.reason}`);
+      }
+      break;
+    }
+
+    case "update": {
+      if (!decision.existing_skill_name || !decision.improved_instructions) {
+        log.debug("Skill update skipped: missing skill name or instructions");
+        return;
+      }
+
+      const updated = skillManager.update(
+        decision.existing_skill_name,
+        decision.improved_instructions,
+        decision.improved_description
+      );
+
+      if (updated) {
+        log.info(`Auto-improved skill "${decision.existing_skill_name}": ${decision.reason}`);
+      } else {
+        log.debug(`Skill update failed: "${decision.existing_skill_name}" not found`);
+      }
+      break;
+    }
+
+    case "skip":
+      log.debug(`Skill evaluation: skip — ${decision.reason}`);
+      break;
+  }
+}
+
+/**
+ * Attempt to parse a SkillDecision from the model's response text.
+ * Tries the full text first (model returned pure JSON), then falls
+ * back to extracting the outermost balanced `{…}` block.
+ */
+function parseJsonResponse(text: string): SkillDecision | null {
+  const trimmed = text.trim();
+
+  // Fast path: entire response is JSON
+  try {
+    const parsed = JSON.parse(trimmed) as SkillDecision;
+    if (parsed.action) return parsed;
+  } catch { /* not pure JSON */ }
+
+  // Fallback: find the first balanced `{…}` block
+  const start = trimmed.indexOf("{");
+  if (start === -1) return null;
+
+  let depth = 0;
+  for (let i = start; i < trimmed.length; i++) {
+    if (trimmed[i] === "{") depth++;
+    else if (trimmed[i] === "}") depth--;
+    if (depth === 0) {
+      try {
+        return JSON.parse(trimmed.slice(start, i + 1)) as SkillDecision;
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}