vellum 0.2.13 → 0.2.14

package/src/config/bundled-skills/playbooks/tools/playbook-delete.ts

@@ -1,9 +1,54 @@
+import { and, eq } from 'drizzle-orm';
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executePlaybookDelete } from '../../../../tools/playbooks/playbook-delete.js';
+import { getDb } from '../../../../memory/db.js';
+import { memoryItems } from '../../../../memory/schema.js';
+import { parsePlaybookStatement } from '../../../../playbooks/types.js';
 
-export async function run(
-  input: Record<string, unknown>,
-  context: ToolContext,
-): Promise<ToolExecutionResult> {
-  return executePlaybookDelete(input, context);
+export async function executePlaybookDelete(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  const playbookId = input.playbook_id as string;
+  if (!playbookId || typeof playbookId !== 'string') {
+    return { content: 'Error: playbook_id is required and must be a string', isError: true };
+  }
+
+  const scopeId = context.memoryScopeId ?? 'default';
+
+  try {
+    const db = getDb();
+
+    const existing = db
+      .select()
+      .from(memoryItems)
+      .where(and(
+        eq(memoryItems.id, playbookId),
+        eq(memoryItems.kind, 'playbook'),
+        eq(memoryItems.scopeId, scopeId),
+      ))
+      .get();
+
+    if (!existing) {
+      return { content: `Error: Playbook with ID "${playbookId}" not found`, isError: true };
+    }
+
+    const playbook = parsePlaybookStatement(existing.statement);
+    const triggerLabel = playbook?.trigger ?? existing.subject;
+
+    // Soft-delete by marking as superseded rather than hard-deleting,
+    // consistent with how other memory items are retired.
+    // Setting invalidAt so the cleanup job can eventually hard-delete it.
+    const now = Date.now();
+    db.update(memoryItems)
+      .set({ status: 'superseded', invalidAt: now })
+      .where(eq(memoryItems.id, existing.id))
+      .run();
+
+    return {
+      content: `Playbook deleted (ID: ${existing.id}, trigger: "${triggerLabel}").`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error deleting playbook: ${msg}`, isError: true };
+  }
 }
+
+export { executePlaybookDelete as run };

package/src/config/bundled-skills/playbooks/tools/playbook-list.ts

@@ -1,9 +1,76 @@
+import { and, desc, eq, isNull } from 'drizzle-orm';
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executePlaybookList } from '../../../../tools/playbooks/playbook-list.js';
+import { getDb } from '../../../../memory/db.js';
+import { memoryItems } from '../../../../memory/schema.js';
+import { parsePlaybookStatement } from '../../../../playbooks/types.js';
 
-export async function run(
-  input: Record<string, unknown>,
-  context: ToolContext,
-): Promise<ToolExecutionResult> {
-  return executePlaybookList(input, context);
+export async function executePlaybookList(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  const scopeId = context.memoryScopeId ?? 'default';
+  const channelFilter = typeof input.channel === 'string' ? input.channel : null;
+  const categoryFilter = typeof input.category === 'string' ? input.category : null;
+
+  try {
+    const db = getDb();
+
+    const rows = db
+      .select({
+        id: memoryItems.id,
+        subject: memoryItems.subject,
+        statement: memoryItems.statement,
+        importance: memoryItems.importance,
+        lastSeenAt: memoryItems.lastSeenAt,
+      })
+      .from(memoryItems)
+      .where(and(
+        eq(memoryItems.kind, 'playbook'),
+        eq(memoryItems.status, 'active'),
+        eq(memoryItems.scopeId, scopeId),
+        isNull(memoryItems.invalidAt),
+      ))
+      .orderBy(desc(memoryItems.importance))
+      .all();
+
+    if (rows.length === 0) {
+      return { content: 'No playbooks found.', isError: false };
+    }
+
+    const entries: Array<{ id: string; subject: string; statement: string; playbook: NonNullable<ReturnType<typeof parsePlaybookStatement>> }> = [];
+    for (const row of rows) {
+      const playbook = parsePlaybookStatement(row.statement);
+      if (!playbook) continue;
+
+      // Apply filters
+      if (channelFilter && playbook.channel !== channelFilter && playbook.channel !== '*') continue;
+      if (categoryFilter && playbook.category !== categoryFilter) continue;
+
+      entries.push({ id: row.id, subject: row.subject, statement: row.statement, playbook });
+    }
+
+    if (entries.length === 0) {
+      const filters = [
+        channelFilter ? `channel="${channelFilter}"` : null,
+        categoryFilter ? `category="${categoryFilter}"` : null,
+      ].filter(Boolean).join(', ');
+      return { content: `No playbooks found matching ${filters}.`, isError: false };
+    }
+
+    // Sort by priority descending
+    entries.sort((a, b) => b.playbook.priority - a.playbook.priority);
+
+    const lines: string[] = [`Found ${entries.length} playbook(s):\n`];
+    for (const { id, playbook } of entries) {
+      const channelLabel = playbook.channel === '*' ? 'all channels' : playbook.channel;
+      const autonomyLabel = playbook.autonomyLevel === 'auto' ? 'auto'
+        : playbook.autonomyLevel === 'draft' ? 'draft' : 'notify';
+      lines.push(`- **${playbook.trigger}** (${channelLabel}) → ${playbook.action}`);
+      lines.push(`  _ID: ${id} | category: ${playbook.category} | autonomy: ${autonomyLabel} | priority: ${playbook.priority}_`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error listing playbooks: ${msg}`, isError: true };
+  }
 }
+
+export { executePlaybookList as run };

package/src/config/bundled-skills/playbooks/tools/playbook-update.ts

@@ -1,9 +1,113 @@
+import { and, eq } from 'drizzle-orm';
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executePlaybookUpdate } from '../../../../tools/playbooks/playbook-update.js';
+import { getDb } from '../../../../memory/db.js';
+import { computeMemoryFingerprint } from '../../../../memory/fingerprint.js';
+import { memoryItems } from '../../../../memory/schema.js';
+import { enqueueMemoryJob } from '../../../../memory/jobs-store.js';
+import { parsePlaybookStatement } from '../../../../playbooks/types.js';
+import type { Playbook, PlaybookAutonomyLevel } from '../../../../playbooks/types.js';
+import { truncate } from '../../../../util/truncate.js';
 
-export async function run(
-  input: Record<string, unknown>,
-  context: ToolContext,
-): Promise<ToolExecutionResult> {
-  return executePlaybookUpdate(input, context);
+const VALID_AUTONOMY_LEVELS = new Set<string>(['auto', 'draft', 'notify']);
+
+export async function executePlaybookUpdate(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  const playbookId = input.playbook_id as string;
+  if (!playbookId || typeof playbookId !== 'string') {
+    return { content: 'Error: playbook_id is required and must be a string', isError: true };
+  }
+
+  const scopeId = context.memoryScopeId ?? 'default';
+
+  try {
+    const db = getDb();
+
+    const existing = db
+      .select()
+      .from(memoryItems)
+      .where(and(
+        eq(memoryItems.id, playbookId),
+        eq(memoryItems.kind, 'playbook'),
+        eq(memoryItems.scopeId, scopeId),
+      ))
+      .get();
+
+    if (!existing) {
+      return { content: `Error: Playbook with ID "${playbookId}" not found`, isError: true };
+    }
+
+    const currentPlaybook = parsePlaybookStatement(existing.statement);
+    if (!currentPlaybook) {
+      return { content: `Error: Playbook data is corrupted for ID "${playbookId}"`, isError: true };
+    }
+
+    // Merge updates onto existing playbook
+    const updated: Playbook = {
+      trigger: typeof input.trigger === 'string' ? input.trigger : currentPlaybook.trigger,
+      channel: typeof input.channel === 'string' ? input.channel : currentPlaybook.channel,
+      category: typeof input.category === 'string' ? input.category : currentPlaybook.category,
+      action: typeof input.action === 'string' ? input.action : currentPlaybook.action,
+      autonomyLevel:
+        typeof input.autonomy_level === 'string' && VALID_AUTONOMY_LEVELS.has(input.autonomy_level)
+          ? (input.autonomy_level as PlaybookAutonomyLevel)
+          : currentPlaybook.autonomyLevel,
+      priority: typeof input.priority === 'number' ? input.priority : currentPlaybook.priority,
+    };
+
+    const statement = JSON.stringify(updated);
+    const subject = truncate(`Playbook: ${updated.trigger}`, 80, '');
+    const now = Date.now();
+
+    const fingerprint = computeMemoryFingerprint(scopeId, 'playbook', subject, statement);
+
+    // Check if another playbook already has this fingerprint
+    const collision = db
+      .select({ id: memoryItems.id })
+      .from(memoryItems)
+      .where(and(
+        eq(memoryItems.fingerprint, fingerprint),
+        eq(memoryItems.scopeId, scopeId),
+      ))
+      .get();
+    if (collision && collision.id !== existing.id) {
+      return {
+        content: `Error: Another playbook with this exact configuration already exists (ID: ${collision.id}).`,
+        isError: true,
+      };
+    }
+
+    db.update(memoryItems)
+      .set({
+        subject,
+        statement,
+        fingerprint,
+        lastSeenAt: now,
+        verificationState: 'user_confirmed',
+      })
+      .where(eq(memoryItems.id, existing.id))
+      .run();
+
+    enqueueMemoryJob('embed_item', { itemId: existing.id });
+
+    const autonomyLabel = updated.autonomyLevel === 'auto' ? 'execute automatically'
+      : updated.autonomyLevel === 'draft' ? 'draft for review' : 'notify only';
+
+    return {
+      content: [
+        'Playbook updated successfully.',
+        `  ID: ${existing.id}`,
+        `  Trigger: ${updated.trigger}`,
+        `  Channel: ${updated.channel}`,
+        `  Category: ${updated.category}`,
+        `  Action: ${updated.action}`,
+        `  Autonomy: ${autonomyLabel}`,
+        `  Priority: ${updated.priority}`,
+      ].join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error updating playbook: ${msg}`, isError: true };
+  }
 }
+
+export { executePlaybookUpdate as run };

package/src/config/bundled-skills/public-ingress/SKILL.md

@@ -68,12 +68,29 @@ ngrok config check
 If not authenticated:
 
 1. Tell the user: "You need an ngrok account to create tunnels. If you don't have one, sign up at https://dashboard.ngrok.com/signup — it's free."
-2. Once they have an account, ask them to paste their auth token directly in chat. They can find it at https://dashboard.ngrok.com/get-started/your-authtoken.
+2. Once they have an account, use `credential_store` to securely collect their auth token. **Never ask the user to paste the token directly in chat.**
 
-3. Once the user provides the token, configure ngrok with it immediately:
-```bash
-ngrok config add-authtoken <token>
-```
+   Use `credential_store` with:
+   - action: `prompt`
+   - service: `ngrok`
+   - field: `authtoken`
+   - label: `ngrok Auth Token`
+   - description: `Get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken`
+   - usage_description: `ngrok authentication token for creating public tunnels`
+
+3. Once the credential is stored, configure ngrok by reading the token directly from the OS keychain and piping it to ngrok so the plaintext never enters the conversation:
+
+   **macOS:**
+   ```bash
+   ngrok config add-authtoken "$(security find-generic-password -s vellum-assistant -a credential:ngrok:authtoken -w)"
+   ```
+
+   **Linux:**
+   ```bash
+   ngrok config add-authtoken "$(secret-tool lookup service vellum-assistant account credential:ngrok:authtoken)"
+   ```
+
+   If the keychain command fails (e.g., headless environment without a keyring), fall back to asking the user to re-enter the token via `credential_store prompt` and then paste it into `ngrok config add-authtoken` manually as a last resort.
 
 Verify authentication succeeded by checking `ngrok config check` again.
 

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

@@ -1,19 +1,113 @@
 ---
 name: "X"
-description: "Read and post on X (formerly Twitter) using your authenticated session"
+description: "Read and post on X (formerly Twitter) via OAuth or browser session"
 user-invocable: true
 metadata: {"vellum": {"emoji": "𝕏"}}
 ---
 
 You are an X (formerly Twitter) assistant. Use the `execute_bash` tool to run `vellum x` CLI commands.
 
+## Connection Options
+
+There are two supported ways to connect to X. Both are fully functional; choose whichever fits the user's situation.
+
+### OAuth (recommended with X developer credentials)
+
+OAuth uses the official X API v2. It is the most reliable connection method and does not depend on browser sessions.
+
+- Supports: **post** and **reply**
+- Read-only operations (timeline, search, home, bookmarks, notifications, likes, followers, following, media) always use the browser path directly, regardless of the strategy setting.
+- Setup: The user connects OAuth credentials through the Settings UI or the `twitter_auth_start` IPC flow.
+- Set the strategy: `vellum x strategy set oauth`
+
+### Browser session (no developer credentials needed)
+
+The browser path is quick to start and useful when the user does not have X developer app credentials. It captures auth cookies from Chrome and uses them to interact with X.
+
+- Supports: **all operations** (post, reply, timeline, search, home, bookmarks, notifications, likes, followers, following, media)
+- Setup: Run `vellum x refresh` to open Chrome and capture session cookies automatically.
+- Set the strategy: `vellum x strategy set browser`
+
+### Auto mode (default)
+
+When the strategy is `auto` (the default), the router tries OAuth first for supported operations if credentials are available, then falls back to the browser path. This gives the best of both worlds without requiring manual switching.
+
+- Set auto mode: `vellum x strategy set auto`
+
+## First-Use Decision Flow
+
+When the user triggers a Twitter operation and no strategy has been configured yet, follow these steps:
+
+1. **Check current status:**
+   ```bash
+   vellum x status --json
+   ```
+   Look at `oauthConnected`, `browserSessionActive`, `preferredStrategy`, and `strategyConfigured` in the response. If `strategyConfigured` is `false`, the user has not yet chosen a strategy and should be guided through setup.
+
+2. **Present both options with trade-offs:**
+   - **OAuth**: Most reliable and official. Requires X developer app credentials (OAuth Client ID and optional Client Secret). Supports posting and replying. Set up through Settings UI.
+   - **Browser session**: Quick to start, no developer credentials needed. Supports all operations including reading timelines and searching. Set up with `vellum x refresh`.
+
+3. **Ask the user which they prefer.** Do not choose for them.
+
+4. **Execute setup for the chosen path:**
+   - If OAuth: Guide the user to the Settings UI to connect their X developer credentials, or initiate the `twitter_auth_start` IPC flow.
+   - If browser: Run `vellum x refresh` to capture session cookies from Chrome.
+
+5. **Set the preferred strategy:**
+   ```bash
+   vellum x strategy set <oauth|browser|auto>
+   ```
+
+## Failure Recovery Flow
+
+When a Twitter operation fails, follow these steps:
+
+1. **Detect the failure type from the error output:**
+   - `session_expired` or `SessionExpiredError` — the browser session cookies have expired.
+   - `OAuth is not configured` — the user chose OAuth but credentials are not set up.
+   - `Twitter API error (401)` — OAuth token may be expired or revoked.
+   - `UnsupportedOAuthOperationError` — the requested write operation is not available via OAuth.
+   - `Cannot connect to daemon` — the Vellum daemon is not running.
+
+2. **Explain the likely cause clearly** to the user.
+
+3. **Suggest trying the other path as an alternative:**
+   - If the browser session expired: suggest setting up OAuth for post/reply operations, or refresh the browser session with `vellum x refresh`.
+   - If OAuth failed or is not configured: suggest using the browser path with `vellum x strategy set browser` and `vellum x refresh`.
+   - If the operation is unsupported via OAuth: explain that this write operation is not yet supported via OAuth, and suggest using the browser path with `vellum x strategy set browser`.
+
+4. **Offer concrete steps to switch:**
+   ```bash
+   # Switch to the other strategy
+   vellum x strategy set <oauth|browser|auto>
+
+   # If switching to browser, refresh the session
+   vellum x refresh
+   ```
+
+## Strategy Management Commands
+
+```bash
+# Check current strategy
+vellum x strategy
+
+# Set strategy to OAuth, browser, or auto
+vellum x strategy set <oauth|browser|auto>
+
+# Check full status (session, OAuth, and strategy info)
+vellum x status --json
+```
+
 ## Posting
 
 ```bash
 vellum x post "The post text here"
 ```
 
-Returns JSON with `ok`, `tweetId`, `text`, and `url` fields. Share the URL with the user so they can verify the post.
+Returns JSON with `ok`, `tweetId`, `text`, `url`, and `pathUsed` fields. The `pathUsed` field indicates whether the post was sent via `oauth` or `browser`. Share the URL with the user so they can verify the post.
+
+The `post` command routes through the strategy router: it uses OAuth if configured and available, otherwise falls back to the browser path.
 
 ## Replying
 
@@ -23,8 +117,12 @@ vellum x reply <tweetUrl> "The reply text here"
 
 The first argument is a tweet URL (e.g. `https://x.com/user/status/123456`) or a bare tweet ID.
 
+Like `post`, the `reply` command routes through the strategy router and returns a `pathUsed` field.
+
 ## Reading
 
+Read-only operations always use the browser path directly, regardless of the strategy setting. They work the same whether the strategy is `oauth`, `browser`, or `auto` — the strategy only affects `post` and `reply` commands.
+
 ### User timeline
 ```bash
 vellum x timeline <screenName> [--count N]
@@ -76,20 +174,6 @@ vellum x media <screenName> [--count N]
 ```
 Returns tweets that contain media from the user's profile.
 
-## Session Management
-
-Check if a session exists:
-```bash
-vellum x status --json
-```
-
-If there is no session or the session has expired, refresh it:
-```bash
-vellum x refresh
-```
-
-This opens Chrome, navigates through x.com automatically, and captures auth cookies. Do NOT tell the user to run this manually — run it yourself.
-
 ## Workflows
 
 ### Check Mentions
@@ -131,4 +215,6 @@ When the user wants to see how their posts are performing:
 - All commands return JSON with an `ok` field
 - When drafting replies, match the tone of the conversation — casual threads get casual replies
 - Always show the user what you're about to post and get approval before sending
-- If a session is expired, refresh it silently with `vellum x refresh` before retrying
+- If a browser session is expired, refresh it with `vellum x refresh` before retrying, or suggest switching to OAuth for post/reply operations
+- If an operation fails, check `vellum x status --json` to diagnose the issue before retrying
+- The `post` and `reply` commands include a `pathUsed` field in their response so you can tell the user which connection method was used

package/src/config/defaults.ts

@@ -76,6 +76,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     },
     jobs: {
       workerConcurrency: 2,
+      batchSize: 10,
     },
     retention: {
       keepRawForever: true,
@@ -117,6 +118,8 @@ export const DEFAULT_CONFIG: AssistantConfig = {
       reaskCooldownTurns: 3,
       resolverLlmTimeoutMs: 12000,
       relevanceThreshold: 0.3,
+      askOnIrrelevantTurns: false,
+      conflictableKinds: ['preference', 'profile', 'constraint', 'instruction', 'style'],
     },
     profile: {
       enabled: true,
@@ -159,7 +162,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     blockIngress: true,
   },
   permissions: {
-    mode: 'strict',
+    mode: 'workspace',
   },
   auditLog: {
     retentionDays: 0,
@@ -233,10 +236,10 @@ export const DEFAULT_CONFIG: AssistantConfig = {
       fallbackToStandardOnError: true,
       elevenlabs: {
         voiceId: '',
-        voiceModelId: 'turbo_v2_5',
+        voiceModelId: '',
+        speed: 1.0,
         stability: 0.5,
         similarityBoost: 0.75,
-        style: 0.0,
         useSpeakerBoost: true,
         agentId: '',
         apiBaseUrl: 'https://api.elevenlabs.io',
@@ -244,9 +247,12 @@ export const DEFAULT_CONFIG: AssistantConfig = {
       },
     },
     model: undefined,
+    callerIdentity: {
+      allowPerCallOverride: true,
+    },
   },
   ingress: {
-    enabled: false,
+    enabled: undefined,
     publicBaseUrl: '',
   },
 };