@vellumai/assistant 0.7.0 → 0.7.2

package/src/daemon/handlers/skills.ts

@@ -31,6 +31,7 @@ import {
   getConfiguredProvider,
   userMessage,
 } from "../../providers/provider-send-message.js";
+import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import {
   isTextMimeType as isTextMime,
   MAX_INLINE_TEXT_SIZE,
@@ -50,7 +51,6 @@ import {
   upsertSkillsIndex,
 } from "../../skills/catalog-install.js";
 import { filterByQuery } from "../../skills/catalog-search.js";
-import type { SkillCategory } from "../../skills/category-inference.js";
 import { inferCategory } from "../../skills/category-inference.js";
 import {
   clawhubCheckUpdates,
@@ -81,36 +81,14 @@ import {
   type SkillAuditData,
 } from "../../skills/skillssh-registry.js";
 import { getWorkspaceSkillsDir } from "../../util/platform.js";
+import { getConfigWatcher } from "../config-watcher.js";
 import { maybeSeedMemoryV2Skills } from "../memory-v2-startup.js";
 import type {
   SkillDetailResponse,
   SkillFileContentResponse,
   SlimSkillResponse,
 } from "../message-types/skills.js";
-
-// Re-export for use by route layer and future consumers.
-export type { SkillCategory };
-export { inferCategory };
-import {
-  CONFIG_RELOAD_DEBOUNCE_MS,
-  ensureSkillEntry,
-  type HandlerContext,
-  log,
-} from "./shared.js";
-
-// ─── Shared context for standalone functions ─────────────────────────────────
-
-/**
- * Minimal context needed by the standalone skill business-logic functions.
- * HandlerContext satisfies this interface, but HTTP routes can also provide
- * a compatible object without coupling to handler internals.
- */
-export interface SkillOperationContext {
-  debounceTimers: HandlerContext["debounceTimers"];
-  setSuppressConfigReload(value: boolean): void;
-  updateConfigFingerprint(): void;
-  broadcast: HandlerContext["broadcast"];
-}
+import { CONFIG_RELOAD_DEBOUNCE_MS, ensureSkillEntry, log } from "./shared.js";
 
 // ─── Provider chain for uninstalled skill file preview ───────────────────────
 // Ordered by priority: vellum first (most common and cheapest to check),
@@ -258,28 +236,25 @@ const LLM_DRAFT_TIMEOUT_MS = 15_000;
 // These are consumed by both the handlers below and the HTTP route layer.
 
 /** Helper: suppress config reload, save, debounce, and update fingerprint. */
-function saveConfigWithSuppression(
-  raw: Record<string, unknown>,
-  ctx: SkillOperationContext,
-): void {
-  ctx.setSuppressConfigReload(true);
+function saveConfigWithSuppression(raw: Record<string, unknown>): void {
+  getConfigWatcher().suppressConfigReload = true;
   try {
     saveRawConfig(raw);
   } catch (err) {
-    ctx.setSuppressConfigReload(false);
+    getConfigWatcher().suppressConfigReload = false;
     throw err;
   }
   invalidateConfigCache();
 
-  ctx.debounceTimers.schedule(
+  getConfigWatcher().timers.schedule(
     "__suppress_reset__",
     () => {
-      ctx.setSuppressConfigReload(false);
+      getConfigWatcher().suppressConfigReload = false;
     },
     CONFIG_RELOAD_DEBOUNCE_MS,
   );
 
-  ctx.updateConfigFingerprint();
+  getConfigWatcher().updateFingerprint();
 }
 
 /**
@@ -296,11 +271,7 @@ function saveConfigWithSuppression(
  * NOT used for bundled skills — those have a simpler inline path in
  * `installSkill()` that only auto-enables, broadcasts, and seeds memories.
  */
-function postInstallSkill(
-  skillId: string,
-  _skillDir: string,
-  ctx: SkillOperationContext,
-): void {
+function postInstallSkill(skillId: string, _skillDir: string): void {
   // Reload skill catalog so the newly installed skill is picked up
   loadSkillCatalog();
 
@@ -308,8 +279,8 @@ function postInstallSkill(
   try {
     const raw = loadRawConfig();
     ensureSkillEntry(raw, skillId).enabled = true;
-    saveConfigWithSuppression(raw, ctx);
-    ctx.broadcast({
+    saveConfigWithSuppression(raw);
+    broadcastMessage({
       type: "skills_state_changed",
       name: skillId,
       state: "enabled",
@@ -413,7 +384,7 @@ function toSlimSkillResponse(
   }
 }
 
-export function listSkills(_ctx: SkillOperationContext): SlimSkillResponse[] {
+export function listSkills(): SlimSkillResponse[] {
   const config = getConfig();
   const catalog = loadSkillCatalog();
   const resolved = resolveSkillStates(catalog, config);
@@ -431,10 +402,8 @@ export function listSkills(_ctx: SkillOperationContext): SlimSkillResponse[] {
  * List installed skills merged with available catalog skills.
  * Installed skills take precedence when deduplicating by ID.
  */
-async function listSkillsWithCatalog(
-  ctx: SkillOperationContext,
-): Promise<SlimSkillResponse[]> {
-  const installed = listSkills(ctx);
+async function listSkillsWithCatalog(): Promise<SlimSkillResponse[]> {
+  const installed = listSkills();
   const installedIds = new Set(installed.map((s) => s.id));
 
   let catalogSkills: CatalogSkill[];
@@ -503,18 +472,15 @@ function originMatchesQuery(origin: string, query: string): boolean {
  * List skills with filtering, category counts, and sorting.
  * Calls listSkillsWithCatalog for the full merged list, then applies filters.
  */
-export async function listSkillsFiltered(
-  filter: SkillListFilter,
-  ctx: SkillOperationContext,
-): Promise<{
+export async function listSkillsFiltered(filter: SkillListFilter): Promise<{
   skills: SlimSkillResponse[];
   categoryCounts: Record<string, number>;
   totalCount: number;
 }> {
   let skills =
     filter.includeCatalog !== false
-      ? await listSkillsWithCatalog(ctx)
-      : listSkills(ctx);
+      ? await listSkillsWithCatalog()
+      : listSkills();
 
   // Apply origin filter
   if (filter.origin) {
@@ -608,7 +574,6 @@ function findSkillById(
 
 export async function getSkill(
   skillId: string,
-  _ctx: SkillOperationContext,
 ): Promise<{ skill: SkillDetailResponse } | { error: string; status: number }> {
   const found = findSkillById(skillId);
   if (!found) {
@@ -812,7 +777,6 @@ function readDirRecursive(dir: string, rootDir: string): SkillFileEntry[] {
 export async function getSkillFileContent(
   skillId: string,
   relativePath: string,
-  _ctx: SkillOperationContext,
 ): Promise<SkillFileContentResponse | { error: string; status: number }> {
   const sanitized = sanitizeRelativePath(relativePath);
   if (!sanitized) {
@@ -935,7 +899,6 @@ export async function getSkillFileContent(
 
 export async function getSkillFiles(
   skillId: string,
-  _ctx: SkillOperationContext,
 ): Promise<
   | { skill: SlimSkillResponse; files: SkillFileEntry[] }
   | { error: string; status: number }
@@ -976,13 +939,12 @@ export async function getSkillFiles(
 
 export function enableSkill(
   skillId: string,
-  ctx: SkillOperationContext,
 ): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
     ensureSkillEntry(raw, skillId).enabled = true;
-    saveConfigWithSuppression(raw, ctx);
-    ctx.broadcast({
+    saveConfigWithSuppression(raw);
+    broadcastMessage({
       type: "skills_state_changed",
       name: skillId,
       state: "enabled",
@@ -1000,13 +962,12 @@ export function enableSkill(
 
 export function disableSkill(
   skillId: string,
-  ctx: SkillOperationContext,
 ): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
     ensureSkillEntry(raw, skillId).enabled = false;
-    saveConfigWithSuppression(raw, ctx);
-    ctx.broadcast({
+    saveConfigWithSuppression(raw);
+    broadcastMessage({
       type: "skills_state_changed",
       name: skillId,
       state: "disabled",
@@ -1029,7 +990,6 @@ export function configureSkill(
     apiKey?: string;
     config?: Record<string, unknown>;
   },
-  ctx: SkillOperationContext,
 ): { success: true } | { success: false; error: string } {
   try {
     const raw = loadRawConfig();
@@ -1037,7 +997,7 @@ export function configureSkill(
     if (config.env) entry.env = config.env;
     if (config.apiKey !== undefined) entry.apiKey = config.apiKey;
     if (config.config) entry.config = config.config;
-    saveConfigWithSuppression(raw, ctx);
+    saveConfigWithSuppression(raw);
     return { success: true };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -1054,15 +1014,12 @@ function looksLikeSkillsShSlug(slug: string): boolean {
   return slug.split("/").length >= 3;
 }
 
-export async function installSkill(
-  spec: {
-    slug: string;
-    version?: string;
-    origin?: "clawhub" | "skillssh";
-    contactId?: string;
-  },
-  ctx: SkillOperationContext,
-): Promise<
+export async function installSkill(spec: {
+  slug: string;
+  version?: string;
+  origin?: "clawhub" | "skillssh";
+  contactId?: string;
+}): Promise<
   { success: true; skillId: string } | { success: false; error: string }
 > {
   try {
@@ -1095,8 +1052,8 @@ export async function installSkill(
       try {
         const raw = loadRawConfig();
         ensureSkillEntry(raw, spec.slug).enabled = true;
-        saveConfigWithSuppression(raw, ctx);
-        ctx.broadcast({
+        saveConfigWithSuppression(raw);
+        broadcastMessage({
           type: "skills_state_changed",
           name: spec.slug,
           state: "enabled",
@@ -1130,7 +1087,7 @@ export async function installSkill(
           );
 
           const skillDir = join(getWorkspaceSkillsDir(), spec.slug);
-          postInstallSkill(spec.slug, skillDir, ctx);
+          postInstallSkill(spec.slug, skillDir);
           return { success: true, skillId: spec.slug };
         }
       } catch (err) {
@@ -1158,7 +1115,7 @@ export async function installSkill(
       );
 
       const skillDir = join(getWorkspaceSkillsDir(), resolved.skillSlug);
-      postInstallSkill(resolved.skillSlug, skillDir, ctx);
+      postInstallSkill(resolved.skillSlug, skillDir);
       return { success: true, skillId: resolved.skillSlug };
     }
 
@@ -1186,7 +1143,7 @@ export async function installSkill(
     }
     upsertSkillsIndex(skillId);
 
-    postInstallSkill(skillId, skillDir, ctx);
+    postInstallSkill(skillId, skillDir);
     return { success: true, skillId };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -1197,7 +1154,6 @@ export async function installSkill(
 
 export async function uninstallSkill(
   skillId: string,
-  ctx: SkillOperationContext,
 ): Promise<{ success: true } | { success: false; error: string }> {
   // Validate skill name to prevent path traversal while allowing namespaced slugs (org/name)
   const validNamespacedSlug =
@@ -1245,10 +1201,10 @@ export async function uninstallSkill(
     const entries = skills?.entries as Record<string, unknown> | undefined;
     if (entries?.[skillId]) {
       delete entries[skillId];
-      saveConfigWithSuppression(raw, ctx);
+      saveConfigWithSuppression(raw);
     }
 
-    ctx.broadcast({
+    broadcastMessage({
       type: "skills_state_changed",
       name: skillId,
       state: "uninstalled",
@@ -1264,7 +1220,6 @@ export async function uninstallSkill(
 
 export async function updateSkill(
   skillId: string,
-  _ctx: SkillOperationContext,
 ): Promise<{ success: true } | { success: false; error: string }> {
   try {
     const result = await clawhubUpdate(skillId);
@@ -1281,9 +1236,7 @@ export async function updateSkill(
   }
 }
 
-export async function checkSkillUpdates(
-  _ctx: SkillOperationContext,
-): Promise<
+export async function checkSkillUpdates(): Promise<
   { success: true; data: unknown } | { success: false; error: string }
 > {
   try {
@@ -1298,7 +1251,6 @@ export async function checkSkillUpdates(
 
 export async function searchSkills(
   query: string,
-  _ctx: SkillOperationContext,
 ): Promise<
   | { success: true; skills: SlimSkillResponse[] }
   | { success: false; error: string }
@@ -1461,7 +1413,6 @@ export async function searchSkills(
 
 export async function inspectSkill(
   skillId: string,
-  _ctx: SkillOperationContext,
 ): Promise<{ slug: string; data?: ClawhubInspectResult; error?: string }> {
   try {
     const result = await clawhubInspect(skillId);
@@ -1490,10 +1441,9 @@ export interface DraftResult {
   error?: string;
 }
 
-export async function draftSkill(
-  params: { sourceText: string },
-  _ctx: SkillOperationContext,
-): Promise<DraftResult> {
+export async function draftSkill(params: {
+  sourceText: string;
+}): Promise<DraftResult> {
   try {
     const warnings: string[] = [];
     const parsed = parseFrontmatter(params.sourceText);
@@ -1645,7 +1595,6 @@ export interface CreateSkillParams {
 
 export async function createSkill(
   params: CreateSkillParams,
-  ctx: SkillOperationContext,
 ): Promise<{ success: true } | { success: false; error: string }> {
   try {
     const result = createManagedSkill({
@@ -1669,8 +1618,8 @@ export async function createSkill(
     try {
       const raw = loadRawConfig();
       ensureSkillEntry(raw, params.skillId).enabled = true;
-      saveConfigWithSuppression(raw, ctx);
-      ctx.broadcast({
+      saveConfigWithSuppression(raw);
+      broadcastMessage({
         type: "skills_state_changed",
         name: params.skillId,
         state: "enabled",

package/src/daemon/host-app-control-proxy.ts

@@ -0,0 +1,293 @@
+/**
+ * Host app-control proxy.
+ *
+ * Proxies app-control actions (start, observe, press, combo, type, click,
+ * drag, stop) to the desktop client. Targets a specific application by
+ * bundle ID or process name — distinct from the system-wide computer-use
+ * proxy ({@link HostCuProxy}).
+ *
+ * Lifecycle (pending map, timeout, abort SSE, dispose, isAvailable) lives
+ * in {@link HostProxyBase}; this class layers app-control-specific state
+ * (PNG-hash loop guard) and the result-payload → ToolExecutionResult
+ * translation on top.
+ *
+ * **Singleton lock.** Only one conversation may hold an active app-control
+ * session at a time. The lock is module-level (`activeAppControlConversationId`)
+ * because a session targets the user's actual desktop application, which
+ * is a host-wide resource. The lock is acquired on a successful
+ * `app_control_start` and released when the owning proxy's `dispose()`
+ * fires. A second conversation that calls `start` while the lock is held
+ * receives an `isError: true` tool result naming the holding conversation.
+ *
+ * **No step cap.** Unlike {@link HostCuProxy} which enforces a per-session
+ * step ceiling via `loadConfig().maxStepsPerSession`, app-control sessions
+ * are not capped. App-control flows are typically narrower (single-app,
+ * shorter horizons) and the loop guard plus user oversight are the
+ * intended safeguards.
+ */
+
+import { createHash } from "node:crypto";
+
+import type { ContentBlock } from "../providers/types.js";
+import type { ToolExecutionResult } from "../tools/types.js";
+import { getLogger } from "../util/logger.js";
+import { HostProxyBase, HostProxyRequestError } from "./host-proxy-base.js";
+import type {
+  HostAppControlInput,
+  HostAppControlResultPayload,
+} from "./message-types/host-app-control.js";
+
+const log = getLogger("host-app-control-proxy");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const REQUEST_TIMEOUT_MS = 60 * 1000;
+// Threshold of 4 means the warning fires on the 5th identical observation:
+// the first observation establishes the baseline (count = 0), each
+// subsequent identical observation increments the counter, so count = 4 is
+// reached on the 5th total observation.
+const STUCK_REPEAT_THRESHOLD = 4;
+
+// ---------------------------------------------------------------------------
+// Tool name constants
+// ---------------------------------------------------------------------------
+//
+// Kept here (rather than imported from PR 5's tool registrations) so the
+// proxy is independently testable. PR 5 must use these same string values.
+
+const TOOL_START = "app_control_start";
+
+// ---------------------------------------------------------------------------
+// Module-level singleton lock
+// ---------------------------------------------------------------------------
+
+/**
+ * Conversation id that currently owns the active app-control session, or
+ * `undefined` if no session is active. Set on a successful
+ * `app_control_start`; cleared by the owning proxy's `dispose()`.
+ *
+ * Exported for test inspection only. Production code paths must not read
+ * or mutate this directly — use the proxy methods.
+ */
+let activeAppControlConversationId: string | undefined;
+
+/** Test-only helper: read current lock owner. */
+export function _getActiveAppControlConversationId(): string | undefined {
+  return activeAppControlConversationId;
+}
+
+/** Test-only helper: clear lock between test cases. */
+export function _resetActiveAppControlConversationId(): void {
+  activeAppControlConversationId = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// HostAppControlProxy
+// ---------------------------------------------------------------------------
+
+export class HostAppControlProxy extends HostProxyBase<
+  HostAppControlInput,
+  HostAppControlResultPayload
+> {
+  /** Conversation that owns this proxy instance. Used by `dispose()` to release the singleton lock only when this proxy is the holder. */
+  private readonly conversationId: string;
+
+  /** sha256 hex of the most recent observation's `pngBase64`, or undefined. */
+  private lastObservationHash?: string;
+
+  /**
+   * Number of consecutive observations whose PNG hash matched the previous
+   * one. Reset to 0 when a different hash is observed. When this reaches
+   * {@link STUCK_REPEAT_THRESHOLD}, results carry a `"stuck"` warning.
+   */
+  private observationHashRepeatCount = 0;
+
+  constructor(conversationId: string) {
+    super({
+      capabilityName: "host_app_control",
+      requestEventName: "host_app_control_request",
+      cancelEventName: "host_app_control_cancel",
+      resultPendingKind: "host_app_control",
+      timeoutMs: REQUEST_TIMEOUT_MS,
+      disposedMessage: "Host app-control proxy disposed",
+    });
+    this.conversationId = conversationId;
+  }
+
+  // ---------------------------------------------------------------------------
+  // State accessors (testing / external inspection)
+  // ---------------------------------------------------------------------------
+
+  get observationRepeatCount(): number {
+    return this.observationHashRepeatCount;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public request entry point
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Dispatch an app-control tool call to the desktop client. Catches the
+   * base's typed lifecycle errors (timeout/aborted/disposed) and returns
+   * a `ToolExecutionResult` instead of letting them bubble.
+   */
+  async request(
+    toolName: string,
+    input: HostAppControlInput,
+    conversationId: string,
+    signal: AbortSignal,
+  ): Promise<ToolExecutionResult> {
+    if (signal.aborted) {
+      return { content: "Aborted", isError: true };
+    }
+
+    // Singleton-lock guard for `start`. Other tools assume a session
+    // already exists and are not gated here.
+    if (toolName === TOOL_START) {
+      if (
+        activeAppControlConversationId != null &&
+        activeAppControlConversationId !== conversationId
+      ) {
+        return {
+          content:
+            `Another conversation (${activeAppControlConversationId}) currently holds the ` +
+            `app-control session. Wait for it to finish, or call app_control_stop ` +
+            `from that conversation first.`,
+          isError: true,
+        };
+      }
+    }
+
+    try {
+      const payload = await this.dispatchRequest(
+        toolName,
+        input,
+        conversationId,
+        signal,
+      );
+      return this.handleSuccess(toolName, payload);
+    } catch (err) {
+      if (err instanceof HostProxyRequestError) {
+        if (err.reason === "timeout") {
+          log.warn({ toolName }, "Host app-control proxy request timed out");
+          return {
+            content:
+              "Host app-control proxy timed out waiting for client response",
+            isError: true,
+          };
+        }
+        if (err.reason === "aborted") {
+          return { content: "Aborted", isError: true };
+        }
+      }
+      // `disposed` and any other unexpected errors propagate.
+      throw err;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Result handling
+  // ---------------------------------------------------------------------------
+
+  private handleSuccess(
+    toolName: string,
+    payload: HostAppControlResultPayload,
+  ): ToolExecutionResult {
+    // Update PNG-hash loop tracking only for the "running" state — other
+    // states (missing/minimized) intentionally won't carry a
+    // representative window screenshot, so they should not feed the guard.
+    let stuck = false;
+    if (payload.state === "running" && payload.pngBase64) {
+      const hash = createHash("sha256").update(payload.pngBase64).digest("hex");
+      if (hash === this.lastObservationHash) {
+        this.observationHashRepeatCount++;
+      } else {
+        this.observationHashRepeatCount = 0;
+      }
+      this.lastObservationHash = hash;
+      if (this.observationHashRepeatCount >= STUCK_REPEAT_THRESHOLD) {
+        stuck = true;
+      }
+    }
+
+    // Acquire the singleton lock on a successful `start`.
+    if (toolName === TOOL_START && payload.state === "running") {
+      activeAppControlConversationId = this.conversationId;
+    }
+
+    return this.formatResult(payload, stuck);
+  }
+
+  private formatResult(
+    payload: HostAppControlResultPayload,
+    stuck: boolean,
+  ): ToolExecutionResult {
+    const parts: string[] = [];
+
+    if (stuck) {
+      parts.push(
+        `WARNING: ${this.observationHashRepeatCount} consecutive observations ` +
+          `produced an identical screenshot — the app appears stuck. Try a ` +
+          `different action or call app_control_stop and restart.`,
+      );
+      parts.push("");
+    }
+
+    parts.push(`State: ${payload.state}`);
+
+    if (payload.windowBounds) {
+      const { x, y, width, height } = payload.windowBounds;
+      parts.push(`Window bounds: ${width}x${height} at (${x}, ${y})`);
+    }
+
+    if (payload.executionResult) {
+      parts.push("");
+      parts.push(payload.executionResult);
+    }
+
+    const isError = payload.executionError != null;
+    const errorPrefix = isError
+      ? `Action failed: ${payload.executionError}`
+      : null;
+
+    const baseContent = parts.join("\n").trim() || `State: ${payload.state}`;
+    const content = errorPrefix
+      ? `${errorPrefix}\n\n${baseContent}`
+      : baseContent;
+
+    const contentBlocks: ContentBlock[] = [];
+    if (payload.pngBase64) {
+      contentBlocks.push({
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: "image/png",
+          data: payload.pngBase64,
+        },
+      });
+    }
+
+    return {
+      content,
+      isError,
+      ...(contentBlocks.length > 0 ? { contentBlocks } : {}),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reject pending requests via the base, then release the singleton lock
+   * if this proxy is the holder. Idempotent: safe to call multiple times.
+   */
+  override dispose(): void {
+    super.dispose();
+    if (activeAppControlConversationId === this.conversationId) {
+      activeAppControlConversationId = undefined;
+    }
+  }
+}