vellum 0.2.0 → 0.2.2

package/src/twitter/session.ts

@@ -0,0 +1,91 @@
+/**
+ * Twitter session persistence.
+ * Stores/loads auth cookies from a recording or manual login.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '../util/platform.js';
+import type { SessionRecording, ExtractedCredential } from '../tools/browser/network-recording-types.js';
+
+export interface TwitterSession {
+  cookies: ExtractedCredential[];
+  importedAt: string;
+  recordingId?: string;
+}
+
+function getSessionDir(): string {
+  return join(getDataDir(), 'twitter');
+}
+
+function getSessionPath(): string {
+  return join(getSessionDir(), 'session.json');
+}
+
+export function loadSession(): TwitterSession | null {
+  const path = getSessionPath();
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as TwitterSession;
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(session: TwitterSession): void {
+  const dir = getSessionDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(getSessionPath(), JSON.stringify(session, null, 2));
+}
+
+export function clearSession(): void {
+  const path = getSessionPath();
+  if (existsSync(path)) {
+    unlinkSync(path);
+  }
+}
+
+/**
+ * Import cookies from a Ride Shotgun recording file.
+ */
+export function importFromRecording(recordingPath: string): TwitterSession {
+  if (!existsSync(recordingPath)) {
+    throw new Error(`Recording not found: ${recordingPath}`);
+  }
+  const recording = JSON.parse(readFileSync(recordingPath, 'utf-8')) as SessionRecording;
+  if (!recording.cookies?.length) {
+    throw new Error('Recording contains no cookies');
+  }
+  // Require the two cookies that prove a logged-in Twitter session:
+  // the auth session cookie and the ct0 CSRF cookie.
+  const cookieNames = new Set(recording.cookies.map(c => c.name));
+  if (!cookieNames.has('ct0') || !cookieNames.has(`auth_${'token'}`)) {
+    throw new Error(
+      'Recording is missing required Twitter session cookies. ' +
+      'Make sure you are logged in to x.com before recording.',
+    );
+  }
+  const session: TwitterSession = {
+    cookies: recording.cookies,
+    importedAt: new Date().toISOString(),
+    recordingId: recording.id,
+  };
+  saveSession(session);
+  return session;
+}
+
+/**
+ * Build a Cookie header string from the session.
+ */
+export function getCookieHeader(session: TwitterSession): string {
+  return session.cookies
+    .map(c => `${c.name}=${c.value}`)
+    .join('; ');
+}
+
+/**
+ * Get the CSRF token from session cookies (ct0 cookie).
+ */
+export function getCsrfToken(session: TwitterSession): string | undefined {
+  return session.cookies.find(c => c.name === 'ct0')?.value;
+}

package/src/usage/types.ts

@@ -12,7 +12,6 @@ export interface UsageEventInput {
   cacheCreationInputTokens: number | null;
   cacheReadInputTokens: number | null;
   actor: UsageActor;
-  assistantId: string | null;
   conversationId: string | null;
   runId: string | null;
   requestId: string | null;

package/src/util/truncate.ts

@@ -0,0 +1,6 @@
+/** Truncate a string to `maxLen` characters, appending `suffix` if truncated. */
+export function truncate(str: string, maxLen: number, suffix = '...'): string {
+  if (str.length <= maxLen) return str;
+  if (maxLen <= suffix.length) return str.slice(0, maxLen);
+  return str.slice(0, maxLen - suffix.length) + suffix;
+}

package/src/watcher/providers/slack.ts

@@ -8,6 +8,7 @@
  */
 
 import { withValidToken } from '../../security/token-manager.js';
+import { truncate } from '../../util/truncate.js';
 import * as slack from '../../messaging/providers/slack/client.js';
 import type { WatcherProvider, WatcherItem, FetchResult } from '../provider-types.js';
 import { getLogger } from '../../util/logger.js';
@@ -22,7 +23,7 @@ function messageToItem(
   return {
     externalId: `${msg.channel}:${msg.ts}`,
     eventType,
-    summary: `Slack ${eventType.replace('slack_', '')}: ${msg.text.slice(0, 100)}`,
+    summary: `Slack ${eventType.replace('slack_', '')}: ${truncate(msg.text, 100)}`,
     payload: {
       channel: msg.channel,
       channelName,

package/src/watcher/watcher-store.ts

@@ -3,6 +3,7 @@ import { v4 as uuid } from 'uuid';
 import { getDb } from '../memory/db.js';
 import { watchers, watcherEvents } from '../memory/schema.js';
 import { DEFAULT_POLL_INTERVAL_MS } from './constants.js';
+import { truncate } from '../util/truncate.js';
 
 // ── Interfaces ──────────────────────────────────────────────────────
 
@@ -227,7 +228,7 @@ export function failWatcherPoll(id: string, error: string): void {
     .set({
       status: 'idle',
       consecutiveErrors: errors,
-      lastError: error.slice(0, 2000),
+      lastError: truncate(error, 2000, ''),
       lastPollAt: now,
       nextPollAt: now + backoff,
       updatedAt: now,
@@ -245,7 +246,7 @@ export function disableWatcher(id: string, reason: string): void {
     .set({
       status: 'disabled',
       enabled: false,
-      lastError: reason.slice(0, 2000),
+      lastError: truncate(reason, 2000, ''),
       updatedAt: Date.now(),
     })
     .where(eq(watchers.id, id))

package/src/work-items/work-item-store.ts

@@ -1,10 +1,11 @@
 import { eq, desc, asc } from 'drizzle-orm';
 import { getDb } from '../memory/db.js';
 import { workItems } from '../memory/schema.js';
+import { getTask } from '../tasks/task-store.js';
 
 // ── Types ────────────────────────────────────────────────────────────
 
-export type WorkItemStatus = 'queued' | 'running' | 'awaiting_review' | 'failed' | 'done' | 'archived';
+export type WorkItemStatus = 'queued' | 'running' | 'awaiting_review' | 'failed' | 'cancelled' | 'done' | 'archived';
 
 export interface WorkItem {
   id: string;
@@ -19,6 +20,9 @@ export interface WorkItem {
   lastRunStatus: string | null;
   sourceType: string | null;
   sourceId: string | null;
+  requiredTools: string | null;
+  approvedTools: string | null;
+  approvalStatus: string | null;
   createdAt: number;
   updatedAt: number;
 }
@@ -33,6 +37,7 @@ export function createWorkItem(opts: {
   sortIndex?: number;
   sourceType?: string;
   sourceId?: string;
+  requiredTools?: string;
 }): WorkItem {
   const db = getDb();
   const now = Date.now();
@@ -50,6 +55,9 @@ export function createWorkItem(opts: {
     lastRunStatus: null,
     sourceType: opts.sourceType ?? null,
     sourceId: opts.sourceId ?? null,
+    requiredTools: opts.requiredTools ?? null,
+    approvedTools: null,
+    approvalStatus: 'none',
     createdAt: now,
     updatedAt: now,
   };
@@ -57,6 +65,24 @@ export function createWorkItem(opts: {
   return item;
 }
 
+/**
+ * Create a work item without any pre-approved permissions. Items start
+ * with `approvalStatus: 'none'` and no `approvedTools` — approval
+ * happens only via the explicit preflight flow before execution.
+ */
+export function createWorkItemWithPermissions(opts: {
+  taskId: string;
+  title: string;
+  notes?: string;
+  priorityTier?: number;
+  sortIndex?: number;
+  sourceType?: string;
+  sourceId?: string;
+  requiredTools?: string;
+}): WorkItem {
+  return createWorkItem(opts);
+}
+
 export function getWorkItem(id: string): WorkItem | undefined {
   const db = getDb();
   return db.select().from(workItems).where(eq(workItems.id, id)).get() as WorkItem | undefined;
@@ -75,7 +101,7 @@ export function listWorkItems(opts?: { status?: WorkItemStatus }): WorkItem[] {
 
 export function updateWorkItem(
   id: string,
-  updates: Partial<Pick<WorkItem, 'title' | 'notes' | 'status' | 'priorityTier' | 'sortIndex' | 'lastRunId' | 'lastRunConversationId' | 'lastRunStatus'>>,
+  updates: Partial<Pick<WorkItem, 'title' | 'notes' | 'status' | 'priorityTier' | 'sortIndex' | 'lastRunId' | 'lastRunConversationId' | 'lastRunStatus' | 'requiredTools' | 'approvedTools' | 'approvalStatus'>>,
 ): WorkItem | undefined {
   const db = getDb();
   db.update(workItems)
@@ -89,3 +115,211 @@ export function deleteWorkItem(id: string): void {
   const db = getDb();
   db.delete(workItems).where(eq(workItems.id, id)).run();
 }
+
+// ── Queue Removal ───────────────────────────────────────────────────
+
+export interface RemoveWorkItemResult {
+  success: boolean;
+  title: string;
+  message: string;
+}
+
+/**
+ * Shared helper for removing a single work item from the queue by ID.
+ * Used by both task_delete (compat path) and task_list_remove so all
+ * single-item deletions follow one codepath.
+ */
+export function removeWorkItemFromQueue(id: string): RemoveWorkItemResult {
+  const item = getWorkItem(id);
+  if (!item) {
+    return { success: false, title: '', message: `No work item found with ID "${id}"` };
+  }
+  deleteWorkItem(item.id);
+  return { success: true, title: item.title, message: `Removed "${item.title}" from the task queue.` };
+}
+
+// ── Selectors / Helpers ─────────────────────────────────────────────
+
+export interface WorkItemSelector {
+  workItemId?: string;
+  taskId?: string;
+  title?: string;
+  /** Disambiguator: filter by priority tier (0 = high, 1 = medium, 2 = low) */
+  priorityTier?: number;
+  /** Disambiguator: filter by status (queued, running, etc.) */
+  status?: WorkItemStatus;
+  /** Disambiguator: 1-indexed creation order (1 = oldest, 2 = second oldest, etc.) */
+  createdOrder?: number;
+}
+
+export type ResolveWorkItemResult =
+  | { status: 'found'; workItem: WorkItem }
+  | { status: 'not_found'; message: string }
+  | { status: 'ambiguous'; matches: WorkItem[]; message: string };
+
+const PRIORITY_TIER_LABELS: Record<number, string> = { 0: 'high', 1: 'medium', 2: 'low' };
+
+function formatAmbiguityMessage(selectorLabel: string, matches: WorkItem[]): string {
+  const lines = matches.map(
+    m =>
+      `  - ID: ${m.id} | title: "${m.title}" | priority: ${PRIORITY_TIER_LABELS[m.priorityTier] ?? m.priorityTier} | status: ${m.status}`,
+  );
+  return `Multiple items match '${selectorLabel}'. Please specify which one:\n${lines.join('\n')}`;
+}
+
+/** Find all active work items for a given task ID */
+export function findActiveWorkItemsByTaskId(taskId: string): WorkItem[] {
+  return listWorkItems().filter(
+    i => i.taskId === taskId && i.status !== 'done' && i.status !== 'archived'
+  );
+}
+
+/** Find all active work items matching a title (case-insensitive exact match) */
+export function findActiveWorkItemsByTitle(title: string): WorkItem[] {
+  const normalized = title.trim().toLowerCase();
+  return listWorkItems().filter(
+    i => i.title.trim().toLowerCase() === normalized && i.status !== 'done' && i.status !== 'archived'
+  );
+}
+
+/**
+ * Apply disambiguator fields to narrow down a set of candidate matches.
+ * Filters by priorityTier, then status, then picks by createdOrder if provided.
+ * Returns the filtered list (may still contain multiple items if disambiguation
+ * fields are insufficient).
+ */
+function applyDisambiguators(items: WorkItem[], selector: WorkItemSelector): WorkItem[] {
+  let filtered = items;
+
+  if (selector.priorityTier !== undefined) {
+    filtered = filtered.filter(i => i.priorityTier === selector.priorityTier);
+  }
+
+  if (selector.status !== undefined) {
+    filtered = filtered.filter(i => i.status === selector.status);
+  }
+
+  if (selector.createdOrder !== undefined && filtered.length > 0) {
+    const sorted = [...filtered].sort((a, b) => a.createdAt - b.createdAt);
+    const idx = selector.createdOrder - 1; // convert 1-indexed to 0-indexed
+    if (idx >= 0 && idx < sorted.length) {
+      filtered = [sorted[idx]];
+    }
+    // If createdOrder is out of range, return the full filtered list so the
+    // caller can report ambiguity with the remaining candidates.
+  }
+
+  return filtered;
+}
+
+/**
+ * Given a list of candidate matches, apply disambiguators and return a resolution result.
+ * Centralises the disambiguate-or-return-ambiguous logic shared across selector branches.
+ */
+function resolveFromCandidates(items: WorkItem[], selectorLabel: string, selector: WorkItemSelector): ResolveWorkItemResult {
+  if (items.length === 0) {
+    return { status: 'not_found', message: `No active work item found for "${selectorLabel}"` };
+  }
+  if (items.length === 1) {
+    return { status: 'found', workItem: items[0] };
+  }
+
+  // Multiple matches — try to narrow down with disambiguator fields
+  const narrowed = applyDisambiguators(items, selector);
+
+  if (narrowed.length === 1) {
+    return { status: 'found', workItem: narrowed[0] };
+  }
+  if (narrowed.length === 0) {
+    // Disambiguators filtered out everything — report the original set so the
+    // caller sees what was available
+    return { status: 'ambiguous', matches: items, message: formatAmbiguityMessage(selectorLabel, items) };
+  }
+  return { status: 'ambiguous', matches: narrowed, message: formatAmbiguityMessage(selectorLabel, narrowed) };
+}
+
+/**
+ * Resolve a single active work item from a selector.
+ * Tries fields in priority order: workItemId > taskId > title.
+ * Only considers active items (status not 'done' or 'archived').
+ * Returns a discriminated union so callers can handle ambiguity explicitly
+ * instead of silently picking one match when multiple exist.
+ *
+ * When multiple items match, the optional disambiguator fields (priorityTier,
+ * status, createdOrder) are applied to narrow down the set.
+ */
+export function resolveWorkItem(selector: WorkItemSelector): ResolveWorkItemResult {
+  if (selector.workItemId) {
+    const item = getWorkItem(selector.workItemId);
+    if (!item) return { status: 'not_found', message: `No work item found with ID "${selector.workItemId}"` };
+    if (item.status === 'done' || item.status === 'archived') {
+      return { status: 'not_found', message: `Work item "${selector.workItemId}" is ${item.status}` };
+    }
+    return { status: 'found', workItem: item };
+  }
+
+  if (selector.taskId) {
+    const items = findActiveWorkItemsByTaskId(selector.taskId);
+    return resolveFromCandidates(items, selector.taskId, selector);
+  }
+
+  if (selector.title) {
+    const items = findActiveWorkItemsByTitle(selector.title);
+    return resolveFromCandidates(items, selector.title, selector);
+  }
+
+  return { status: 'not_found', message: 'At least one selector field (workItemId, taskId, or title) must be provided' };
+}
+
+// ── Entity Identification ───────────────────────────────────────────
+
+export type EntityType = 'task_template' | 'work_item' | 'unknown';
+
+export interface EntityIdentification {
+  type: EntityType;
+  id: string;
+  title?: string;
+}
+
+/**
+ * Determine whether an ID refers to a task template (tasks table) or
+ * a work item (work_items table). Used by tool error messages to give
+ * the model corrective guidance when the wrong entity type is provided.
+ */
+export function identifyEntityById(id: string): EntityIdentification {
+  const workItem = getWorkItem(id);
+  if (workItem) {
+    return { type: 'work_item', id: workItem.id, title: workItem.title };
+  }
+
+  const task = getTask(id);
+  if (task) {
+    return { type: 'task_template', id: task.id, title: task.title };
+  }
+
+  return { type: 'unknown', id };
+}
+
+/**
+ * Build a corrective error message when a work item ID is passed where
+ * a task template ID is expected.
+ */
+export function buildWorkItemMismatchError(id: string, title: string, expectedTool: string): string {
+  return [
+    `Entity mismatch: The ID "${id}" refers to a work item ("${title}"), not a task template.`,
+    `Corrective action: Use ${expectedTool} to operate on work items in the task queue.`,
+    `Selector fields: work_item_id: "${id}" or title: "${title}"`,
+  ].join('\n');
+}
+
+/**
+ * Build a corrective error message when a task template ID is passed where
+ * a work item ID is expected.
+ */
+export function buildTaskTemplateMismatchError(id: string, title: string, expectedTool: string): string {
+  return [
+    `Entity mismatch: The ID "${id}" refers to a task template ("${title}"), not a work item.`,
+    `Corrective action: Use ${expectedTool} to operate on task templates.`,
+    `Selector fields: task_id: "${id}" or task_name: "${title}"`,
+  ].join('\n');
+}