@vellumai/assistant 0.6.5 → 0.6.6

package/src/cli/commands/shotgun.ts

@@ -1,266 +0,0 @@
-import { randomUUID } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { join } from "node:path";
-
-import type { Command } from "commander";
-
-import { getSignalsDir } from "../../util/platform.js";
-import { log } from "../logger.js";
-
-const POLL_INTERVAL_MS = 100;
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-interface ShotgunResult {
-  requestId: string;
-  ok: boolean;
-  error?: string;
-  watchId?: string;
-  conversationId?: string;
-  status?: string;
-}
-
-function writeShotgunSignal(
-  requestId: string,
-  payload: Record<string, unknown>,
-): { signalPath: string; resultPath: string } | null {
-  const signalsDir = getSignalsDir();
-  try {
-    mkdirSync(signalsDir, { recursive: true });
-  } catch {
-    log.error("Failed to create signals directory.");
-    return null;
-  }
-
-  const signalPath = join(signalsDir, `shotgun.${requestId}`);
-  const resultPath = join(signalsDir, `shotgun.${requestId}.result`);
-
-  try {
-    writeFileSync(signalPath, JSON.stringify({ requestId, ...payload }));
-  } catch {
-    log.error("Failed to write shotgun signal file.");
-    return null;
-  }
-
-  return { signalPath, resultPath };
-}
-
-function pollForResult(
-  requestId: string,
-  resultPath: string,
-  signalPath: string,
-  timeoutMs: number,
-  callback: (result: ShotgunResult) => void,
-): void {
-  const deadline = Date.now() + timeoutMs + 5_000;
-
-  const poll = setInterval(() => {
-    if (Date.now() > deadline) {
-      clearInterval(poll);
-      cleanup(signalPath, resultPath);
-      log.error("Timed out waiting for response. Is the assistant running?");
-      process.exitCode = 1;
-      return;
-    }
-
-    if (!existsSync(resultPath)) return;
-
-    let result: ShotgunResult;
-    try {
-      const content = readFileSync(resultPath, "utf-8");
-      result = JSON.parse(content) as ShotgunResult;
-    } catch {
-      return;
-    }
-
-    if (result.requestId !== requestId) return;
-
-    clearInterval(poll);
-    cleanup(signalPath, resultPath);
-    callback(result);
-  }, POLL_INTERVAL_MS);
-}
-
-function cleanup(...paths: string[]): void {
-  for (const p of paths) {
-    try {
-      unlinkSync(p);
-    } catch {
-      // Best-effort cleanup.
-    }
-  }
-}
-
-export function registerShotgunCommand(program: Command): void {
-  const shotgun = program
-    .command("shotgun")
-    .description("Start and monitor screen-watch (shotgun) sessions via IPC");
-
-  shotgun.addHelpText(
-    "after",
-    `
-Screen-watch sessions capture periodic screenshots and feed them to the
-assistant for observation. The CLI communicates with the running assistant
-via IPC signal files — the assistant must be running for these commands
-to work.
-
-Examples:
-  $ assistant shotgun start --duration 600 --focus "browsing workflow"
-  $ assistant shotgun status <watchId>`,
-  );
-
-  shotgun
-    .command("start")
-    .description("Start a new screen-watch session")
-    .option(
-      "-d, --duration <seconds>",
-      "Duration in seconds for the watch session",
-      "300",
-    )
-    .option("-i, --interval <seconds>", "Seconds between screen captures", "5")
-    .option(
-      "-f, --focus <area>",
-      "What to focus on observing",
-      "general observation",
-    )
-    .option(
-      "-t, --timeout <ms>",
-      "Timeout in milliseconds waiting for the assistant to respond",
-      String(DEFAULT_TIMEOUT_MS),
-    )
-    .addHelpText(
-      "after",
-      `
-Starts a screen-watch session via IPC signal files. The assistant
-creates a watch session and begins accepting screen observations from the
-desktop client.
-
-The CLI writes the request to signals/shotgun.<requestId> and polls
-signals/shotgun.<requestId>.result for the response. The assistant must
-be running for this to work.
-
-Output (JSON): { ok, watchId, conversationId }
-
-Examples:
-  $ assistant shotgun start
-  $ assistant shotgun start --duration 600 --interval 10 --focus "doordash.com"
-  $ assistant shotgun start -d 300 -i 5 -f "browsing workflow"`,
-    )
-    .action(
-      (opts: {
-        duration: string;
-        interval: string;
-        focus: string;
-        timeout: string;
-      }) => {
-        const durationSeconds = parseInt(opts.duration, 10);
-        if (!Number.isFinite(durationSeconds) || durationSeconds < 1) {
-          log.error("Invalid duration. Must be a positive integer.");
-          process.exitCode = 1;
-          return;
-        }
-
-        const intervalSeconds = parseInt(opts.interval, 10);
-        if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1) {
-          log.error("Invalid interval. Must be a positive integer.");
-          process.exitCode = 1;
-          return;
-        }
-
-        const timeoutMs = parseInt(opts.timeout, 10);
-        if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
-          log.error("Invalid timeout. Must be a positive integer.");
-          process.exitCode = 1;
-          return;
-        }
-
-        const requestId = randomUUID();
-        const paths = writeShotgunSignal(requestId, {
-          action: "start",
-          durationSeconds,
-          intervalSeconds,
-          focusArea: opts.focus,
-        });
-        if (!paths) {
-          process.exitCode = 1;
-          return;
-        }
-
-        pollForResult(
-          requestId,
-          paths.resultPath,
-          paths.signalPath,
-          timeoutMs,
-          (result) => {
-            if (!result.ok) {
-              process.stdout.write(JSON.stringify(result) + "\n");
-              process.exitCode = 1;
-              return;
-            }
-            process.stdout.write(JSON.stringify(result) + "\n");
-          },
-        );
-      },
-    );
-
-  shotgun
-    .command("status <watchId>")
-    .description("Check the status of an active screen-watch session")
-    .option(
-      "-t, --timeout <ms>",
-      "Timeout in milliseconds waiting for the assistant to respond",
-      String(DEFAULT_TIMEOUT_MS),
-    )
-    .addHelpText(
-      "after",
-      `
-Arguments:
-  watchId   The watch session ID returned by 'assistant shotgun start'.
-
-Queries the status of an existing screen-watch session by watchId.
-
-Output (JSON): { ok, watchId, conversationId, status }
-
-The status field is one of: "active", "completing", "completed", "cancelled".
-
-Examples:
-  $ assistant shotgun status abc12345
-  $ assistant shotgun status abc12345 --timeout 5000`,
-    )
-    .action((watchId: string, opts: { timeout: string }) => {
-      const timeoutMs = parseInt(opts.timeout, 10);
-      if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
-        log.error("Invalid timeout. Must be a positive integer.");
-        process.exitCode = 1;
-        return;
-      }
-
-      const requestId = randomUUID();
-      const paths = writeShotgunSignal(requestId, {
-        action: "status",
-        watchId,
-      });
-      if (!paths) {
-        process.exitCode = 1;
-        return;
-      }
-
-      pollForResult(
-        requestId,
-        paths.resultPath,
-        paths.signalPath,
-        timeoutMs,
-        (result) => {
-          process.stdout.write(JSON.stringify(result) + "\n");
-          if (!result.ok) {
-            process.exitCode = 1;
-          }
-        },
-      );
-    });
-}

package/src/config/bundled-skills/conversations/SKILL.md

@@ -1,20 +0,0 @@
----
-name: conversations
-description: Manage conversation threads (rename)
-compatibility: "Designed for Vellum personal assistants"
-metadata:
-  emoji: "\U0001F4AC"
-  vellum:
-    display-name: "Conversations"
----
-
-Tools for managing conversation threads.
-
-## Renaming
-
-Use the `rename_conversation` tool to rename the current conversation thread when:
-- The topic has shifted significantly from the original title
-- The auto-generated title is generic or unhelpful
-- The user explicitly asks to rename the thread
-
-Keep titles concise (under 60 characters) and descriptive of the current topic.

package/src/config/bundled-skills/conversations/TOOLS.json

@@ -1,23 +0,0 @@
-{
-  "version": 1,
-  "tools": [
-    {
-      "name": "rename_conversation",
-      "description": "Rename the current conversation thread. Use this when the conversation topic has shifted significantly from the original title, or when you notice the title is generic/unhelpful and you can provide a better one based on what has been discussed.",
-      "category": "conversation",
-      "risk": "low",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "title": {
-            "type": "string",
-            "description": "The new title for the conversation. Should be concise (under 60 characters) and descriptive of the current topic."
-          }
-        },
-        "required": ["title"]
-      },
-      "executor": "tools/rename-conversation.ts",
-      "execution_target": "host"
-    }
-  ]
-}

package/src/config/bundled-skills/conversations/tools/rename-conversation.ts

@@ -1,88 +0,0 @@
-import {
-  getConversation,
-  updateConversationTitle,
-} from "../../../../memory/conversation-crud.js";
-import { buildAssistantEvent } from "../../../../runtime/assistant-event.js";
-import { assistantEventHub } from "../../../../runtime/assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../../../runtime/assistant-scope.js";
-import type {
-  ToolContext,
-  ToolExecutionResult,
-} from "../../../../tools/types.js";
-import { getLogger } from "../../../../util/logger.js";
-
-const log = getLogger("rename-conversation");
-
-export async function run(
-  input: Record<string, unknown>,
-  context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const title = input.title;
-  if (typeof title !== "string" || title.trim() === "") {
-    return {
-      content: "Error: title must be a non-empty string.",
-      isError: true,
-    };
-  }
-
-  const trimmedTitle = title.trim();
-  const conversationId = context.conversationId;
-
-  const conversation = getConversation(conversationId);
-  if (!conversation) {
-    return {
-      content: `Error: conversation ${conversationId} not found.`,
-      isError: true,
-    };
-  }
-
-  // Persist with isAutoTitle = 0 so auto-generation won't overwrite it
-  updateConversationTitle(conversationId, trimmedTitle, 0);
-
-  // Notify the client currently viewing this conversation so the header
-  // updates in-place. Scoped to this conversation so foreign
-  // `conversationId` values don't leak to other subscribers' speculative
-  // ID-resolution paths. Other clients learn about the rename via the
-  // unscoped `conversation_list_invalidated` published below, which
-  // triggers their sidebars to refetch and pick up the new title.
-  const assistantId = context.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
-  assistantEventHub
-    .publish(
-      buildAssistantEvent(
-        assistantId,
-        {
-          type: "conversation_title_updated",
-          conversationId,
-          title: trimmedTitle,
-        },
-        conversationId,
-      ),
-    )
-    .catch((err) => {
-      log.warn({ err }, "Failed to publish conversation_title_updated event");
-    });
-
-  // Broadcast `conversation_list_invalidated` unscoped so every connected
-  // client's sidebar refetches and picks up the renamed title. Mirrors
-  // the HTTP rename route in `conversation-management-routes.ts`.
-  assistantEventHub
-    .publish(
-      buildAssistantEvent(assistantId, {
-        type: "conversation_list_invalidated",
-        reason: "renamed",
-      }),
-    )
-    .catch((err) => {
-      log.warn(
-        { err },
-        "Failed to publish conversation_list_invalidated for rename",
-      );
-    });
-
-  log.info({ conversationId, title: trimmedTitle }, "Conversation renamed");
-
-  return {
-    content: `Conversation renamed to "${trimmedTitle}".`,
-    isError: false,
-  };
-}

package/src/config/bundled-skills/heartbeat/SKILL.md

@@ -1,43 +0,0 @@
----
-name: heartbeat
-description: Configure periodic background checklist runs
-compatibility: "Designed for Vellum personal assistants"
-metadata:
-  emoji: "\U0001F493"
-  vellum:
-    display-name: "Heartbeat"
-    activation-hints:
-      - "Set up a heartbeat, periodic checklist, background health check, or recurring background task"
-    avoid-when:
-      - "One-off or recurring schedules with specific payloads - use the schedule skill instead"
----
-
-The heartbeat feature runs your `HEARTBEAT.md` checklist periodically in a background conversation. Each run, the assistant works through the checklist and flags anything that needs attention.
-
-## Setup
-
-Edit `config.json` using `file_edit`:
-
-1. **Enable heartbeat**: Set `heartbeat.enabled` to `true`.
-2. **Set interval**: Set `heartbeat.intervalMs` (milliseconds between runs, default: 3600000 = 1 hour).
-3. **Optional active hours**: Set `heartbeat.activeHoursStart` and `heartbeat.activeHoursEnd` (0-23) to restrict runs to certain hours. Both must be set together.
-
-Example config.json heartbeat section:
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "intervalMs": 1800000,
-    "activeHoursStart": 8,
-    "activeHoursEnd": 22
-  }
-}
-```
-
-Then edit `HEARTBEAT.md` with the checklist items. The assistant will work through this file each heartbeat run.
-
-## Notes
-
-- Toggling `heartbeat.enabled` requires an assistant restart to take effect.
-- Changes to `HEARTBEAT.md` take effect on the next heartbeat run (no restart needed).
-- The heartbeat runs in a separate background conversation, not the user's active chat.

package/src/config/bundled-skills/notifications/SKILL.md

@@ -1,40 +0,0 @@
----
-name: notifications
-description: Send notifications through the unified notification router
-compatibility: "Designed for Vellum personal assistants"
-metadata:
-  emoji: "🔔"
-  vellum:
-    display-name: "Notifications"
----
-
-Use `send_notification` for user-facing alerts and notifications. This tool routes through the unified notification pipeline, which handles channel selection, delivery, deduplication, and audit logging.
-
-## Routing Behavior
-
-- `preferred_channels` are **routing hints**, not hard channel forcing. The notification router makes the final delivery decision based on user preferences, channel availability, and urgency.
-- Channel selection and delivery are handled entirely by the notification router -- do not attempt to control delivery manually.
-
-## Deduplication (`dedupe_key`)
-
-- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused - any future notification with the same key will be silently discarded.
-- Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
-- If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
-
-## Conversation Grouping
-
-Conversation grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to conversation X" parameter - conversation reuse is inferred, not commanded.
-
-**How it works:** The engine evaluates recent notification conversation candidates and decides whether a new signal is a continuation of an existing conversation based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies - the engine groups by semantic relatedness, not string matching.
-
-**`source_event_name` is the primary grouping signal.** Use a stable event name for notifications that belong to the same logical stream (e.g. `dog.news.thread.reply` for all replies in a thread). Use a distinct event name when the notification represents a genuinely different kind of event.
-
-**Practical constraints:**
-
-- Conversation candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old conversation from days ago.
-- The engine will only reuse conversations originally created by the notification system (`source === 'notification'`). It will never append to a user-initiated conversation, even if it looks related.
-
-## Important
-
-- Do **NOT** use AppleScript `display notification` or other OS-level notification commands for assistant-managed alerts. Always use `send_notification`.
-- For sending rich content (digests, summaries, reports) to a specific chat or email destination, use the appropriate platform's API directly. For Gmail, use `messaging_send`. For Slack, use the Slack Web API directly (see the **slack** skill). The decision engine rewrites `send_notification` content into short alerts, which strips rich formatting.

package/src/config/bundled-skills/notifications/TOOLS.json

@@ -1,80 +0,0 @@
-{
-  "version": 1,
-  "tools": [
-    {
-      "name": "send_notification",
-      "description": "Send an immediate notification. Fires instantly with no delay capability. For one-time future alerts, use schedule_create with fire_at. For recurring alerts, use schedule_create with expression (cron/RRULE). The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
-      "category": "notifications",
-      "risk": "medium",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "message": {
-            "type": "string",
-            "description": "Notification message the user should receive"
-          },
-          "title": {
-            "type": "string",
-            "description": "Optional notification title"
-          },
-          "urgency": {
-            "type": "string",
-            "enum": ["low", "medium", "high"],
-            "description": "Urgency hint (default: \"medium\")"
-          },
-          "requires_action": {
-            "type": "boolean",
-            "description": "Whether the notification expects user action (default: true)"
-          },
-          "is_async_background": {
-            "type": "boolean",
-            "description": "Whether the event is asynchronous/background work (default: false)"
-          },
-          "visible_in_source_now": {
-            "type": "boolean",
-            "description": "Set true when user is already viewing the source context (default: false)"
-          },
-          "deadline_at": {
-            "type": "number",
-            "description": "Optional deadline timestamp in epoch milliseconds"
-          },
-          "preferred_channels": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "enum": ["vellum", "telegram", "slack"]
-            },
-            "description": "Optional routing hints for preferred channels (not deterministic)"
-          },
-          "conversation_id": {
-            "type": "string",
-            "description": "Optional source conversation ID for notification context"
-          },
-          "source_event_name": {
-            "type": "string",
-            "description": "Optional event name for audit and dedupe grouping (default: \"user.send_notification\")"
-          },
-          "deep_link_metadata": {
-            "type": "object",
-            "description": "Optional metadata clients can use for deep linking"
-          },
-          "dedupe_key": {
-            "type": "string",
-            "description": "Optional dedupe key to suppress duplicate notifications"
-          },
-          "confidence": {
-            "type": "number",
-            "description": "Confidence score (0-1) for this action"
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
-          }
-        },
-        "required": ["message", "confidence"]
-      },
-      "executor": "tools/send-notification.ts",
-      "execution_target": "host"
-    }
-  ]
-}