assistme 0.2.9 → 0.3.0

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) {
@@ -605,7 +616,78 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
         }
       ),
 
-      // ── User Confirmation Tool ─────────────────────────────────
+      // ── User Interaction Tools ──────────────────────────────────
+
+      tool(
+        "request_user_input",
+        "Ask the user a clarifying question and wait for their free-text response. " +
+          "Use this when you need information that cannot be inferred from context, memory, or the workspace — " +
+          "e.g. which account to use, specific preferences, ambiguous instructions, or missing parameters for a skill. " +
+          "Do NOT use this for information you can discover yourself (git remote, file contents, etc.).",
+        {
+          question: z.string().describe("The question to ask the user (supports markdown). Be specific about what you need and why."),
+          placeholder: z.string().optional().describe("Placeholder text for the input field (e.g. 'https://github.com/owner/repo')"),
+          timeout_seconds: z.number().optional().describe("How long to wait for response (default: 300)"),
+        },
+        async (args) => {
+          const actionId = `input_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+          const timeout = (args.timeout_seconds || 300) * 1000;
+
+          const actionData = {
+            id: actionId,
+            type: "input",
+            message: args.question,
+            placeholder: args.placeholder || "",
+            created_at: new Date().toISOString(),
+          };
+
+          try {
+            await setActionRequest(taskId, actionData);
+            log.info(`Input request ${actionId}: "${args.question.slice(0, 80)}..."`);
+
+            emitEvent(taskId, "user_action_request", actionData).catch(() => {});
+
+            const startTime = Date.now();
+            const pollInterval = 2000;
+
+            while (Date.now() - startTime < timeout) {
+              const response = await pollActionResponse(taskId);
+              // Match response to this specific request by action_id
+              if (response && (!response.action_id || response.action_id === actionId)) {
+                const text = (response.text || response.value || "") as string;
+                log.info(`User input received: "${text.slice(0, 80)}"`);
+                return {
+                  content: [{
+                    type: "text",
+                    text: JSON.stringify({ status: "responded", text }),
+                  }],
+                };
+              }
+
+              await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            }
+
+            log.warn(`Input request ${actionId} timed out`);
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  status: "timeout",
+                  message: "User did not respond within the timeout period.",
+                }),
+              }],
+            };
+          } catch (err) {
+            log.error(`request_user_input failed: ${err}`);
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to request user input: ${err instanceof Error ? err.message : err}`,
+              }],
+            };
+          }
+        }
+      ),
 
       tool(
         "request_user_confirmation",
@@ -647,7 +729,8 @@ export function createAgentToolsServer(deps: AgentToolsDeps): McpSdkServerConfig
 
             while (Date.now() - startTime < timeout) {
               const response = await pollActionResponse(taskId);
-              if (response) {
+              // Match response to this specific request by action_id
+              if (response && (!response.action_id || response.action_id === actionId)) {
                 const actionKey = (response.action_key || response.action || "") as string;
                 const label = (response.label || actionKey) as string;
                 log.info(`User responded: ${label} (${actionKey})`);

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,13 +59,25 @@ 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
@@ -101,6 +114,14 @@ 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 request_user_input 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 request_user_input. Do NOT guess, assume defaults, or proceed with incomplete information.
+- 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 +153,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 +185,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 +207,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,7 +276,8 @@ export class TaskProcessor {
         "mcp__assistme-agent__skill_browse",
         "mcp__assistme-agent__skill_add",
         "mcp__assistme-agent__skill_publish",
-        // User confirmation
+        // User interaction
+        "mcp__assistme-agent__request_user_input",
         "mcp__assistme-agent__request_user_confirmation",
         // Job automation tools
         "mcp__assistme-agent__job_run",
@@ -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;
+}