vellum 0.2.0 → 0.2.1

package/src/runtime/routes/run-routes.ts

@@ -11,7 +11,6 @@ import type { RunOrchestrator } from '../run-orchestrator.js';
 const log = getLogger('runtime-http');
 
 export async function handleCreateRun(
-  assistantId: string,
   req: Request,
   runOrchestrator: RunOrchestrator,
 ): Promise<Response> {
@@ -39,7 +38,7 @@ export async function handleCreateRun(
   }
 
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds(assistantId, attachmentIds);
+    const resolved = attachmentsStore.getAttachmentsByIds("self", attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
@@ -50,11 +49,10 @@ export async function handleCreateRun(
     }
   }
 
-  const mapping = getOrCreateConversation(assistantId, conversationKey);
+  const mapping = getOrCreateConversation("self", conversationKey);
 
   try {
     const run = await runOrchestrator.startRun(
-      assistantId,
       mapping.conversationId,
       content ?? '',
       hasAttachments ? attachmentIds : undefined,
@@ -77,12 +75,11 @@ export async function handleCreateRun(
 }
 
 export function handleGetRun(
-  assistantId: string,
   runId: string,
   runOrchestrator: RunOrchestrator,
 ): Response {
   const run = runOrchestrator.getRun(runId);
-  if (!run || run.assistantId !== assistantId) {
+  if (!run) {
     return Response.json({ error: 'Run not found' }, { status: 404 });
   }
 
@@ -98,13 +95,12 @@ export function handleGetRun(
 }
 
 export async function handleRunDecision(
-  assistantId: string,
   runId: string,
   req: Request,
   runOrchestrator: RunOrchestrator,
 ): Promise<Response> {
   const run = runOrchestrator.getRun(runId);
-  if (!run || run.assistantId !== assistantId) {
+  if (!run) {
     return Response.json({ error: 'Run not found' }, { status: 404 });
   }
 

package/src/runtime/run-orchestrator.ts

@@ -18,6 +18,8 @@ import type { UserDecision } from '../permissions/types.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
 import { IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
+import { assistantEventHub } from './assistant-event-hub.js';
+import { buildAssistantEvent } from './assistant-event.js';
 
 const log = getLogger('run-orchestrator');
 
@@ -32,7 +34,7 @@ interface PendingRunState {
 
 export interface RunOrchestratorDeps {
   getOrCreateSession: (conversationId: string) => Promise<Session>;
-  resolveAttachments: (assistantId: string, attachmentIds: string[]) => Array<{
+  resolveAttachments: (attachmentIds: string[]) => Array<{
     id: string;
     filename: string;
     mimeType: string;
@@ -64,7 +66,6 @@ export class RunOrchestrator {
    * and fire the agent loop in the background.
    */
   async startRun(
-    assistantId: string,
     conversationId: string,
     content: string,
     attachmentIds?: string[],
@@ -82,15 +83,32 @@ export class RunOrchestrator {
     }
 
     const attachments = attachmentIds
-      ? this.deps.resolveAttachments(assistantId, attachmentIds)
+      ? this.deps.resolveAttachments(attachmentIds)
       : [];
 
     const requestId = crypto.randomUUID();
     const messageId = session.persistUserMessage(content, attachments, requestId);
-    const run = runsStore.createRun(assistantId, conversationId, messageId);
+    const run = runsStore.createRun('self', conversationId, messageId);
 
     // Set the assistant ID so attachments are scoped correctly.
-    session.setAssistantId(assistantId);
+    session.setAssistantId('self');
+
+    // Serialized publish chain so hub subscribers observe events in order.
+    let hubChain: Promise<void> = Promise.resolve();
+    const publishToHub = (msg: ServerMessage): void => {
+      const msgRecord = msg as unknown as Record<string, unknown>;
+      const msgSessionId =
+        'sessionId' in msg && typeof msgRecord.sessionId === 'string'
+          ? (msgRecord.sessionId as string)
+          : undefined;
+      const resolvedSessionId = msgSessionId ?? conversationId;
+      const event = buildAssistantEvent('self', msg, resolvedSessionId);
+      hubChain = hubChain
+        .then(() => assistantEventHub.publish(event))
+        .catch((err: unknown) => {
+          log.warn({ err }, 'assistant-events hub subscriber threw during HTTP run');
+        });
+    };
 
     // Hook into session to intercept confirmation_request events.
     // When the prompter sends a confirmation_request, we record it in the
@@ -118,6 +136,9 @@ export class RunOrchestrator {
           session,
         });
       }
+      // Mirror every outbound message to the assistant-events hub so SSE
+      // subscribers receive the same payload parity as IPC clients.
+      publishToHub(msg);
     });
 
     // Fire-and-forget the agent loop
@@ -136,6 +157,12 @@ export class RunOrchestrator {
       } else if (msg.type === 'session_error') {
         lastError = msg.userMessage;
       }
+      // Mirror agent-loop events (assistant_text_delta, message_complete,
+      // tool_use_start, tool_result, etc.) to the hub. These travel through
+      // the onEvent path, distinct from the updateClient path used by the
+      // prompter (confirmation_request). Both paths must publish so SSE
+      // consumers receive the full response stream.
+      publishToHub(msg);
     }).then(() => {
       if (lastError) {
         log.error({ runId: run.id, error: lastError }, 'Run failed (error event from agent loop)');

package/src/tools/calls/call-end.ts

@@ -0,0 +1,117 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { getCallSession, updateCallSession } from '../../calls/call-store.js';
+import { getCallOrchestrator, unregisterCallOrchestrator } from '../../calls/call-state.js';
+import { activeRelayConnections } from '../../calls/relay-server.js';
+import { TwilioConversationRelayProvider } from '../../calls/twilio-provider.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('call-end');
+
+const definition: ToolDefinition = {
+  name: 'call_end',
+  description: 'End an active phone call',
+  input_schema: {
+    type: 'object',
+    properties: {
+      call_session_id: {
+        type: 'string',
+        description: 'The call session ID to end',
+      },
+      reason: {
+        type: 'string',
+        description: 'Reason for ending the call',
+      },
+    },
+    required: ['call_session_id'],
+  },
+};
+
+class CallEndTool implements Tool {
+  name = 'call_end';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const callSessionId = input.call_session_id as string | undefined;
+    if (!callSessionId || typeof callSessionId !== 'string') {
+      return { content: 'Error: call_session_id is required and must be a string', isError: true };
+    }
+
+    const reason = input.reason as string | undefined;
+
+    try {
+      const session = getCallSession(callSessionId);
+      if (!session) {
+        return { content: `Error: no call session found with ID ${callSessionId}`, isError: true };
+      }
+
+      if (session.status === 'completed' || session.status === 'failed') {
+        return {
+          content: `Call session ${callSessionId} has already ended with status: ${session.status}`,
+          isError: false,
+        };
+      }
+
+      log.info({ callSessionId, reason }, 'Ending call');
+
+      // Terminate the call via the provider API so Twilio hangs up,
+      // even if the relay WebSocket is not connected.
+      if (session.providerCallSid) {
+        try {
+          const provider = new TwilioConversationRelayProvider();
+          await provider.endCall(session.providerCallSid);
+        } catch (endErr) {
+          log.warn({ err: endErr, callSessionId, callSid: session.providerCallSid }, 'Failed to terminate call via provider API — proceeding with cleanup');
+        }
+      }
+
+      // End the relay connection if active
+      const relayConnection = activeRelayConnections.get(callSessionId);
+      if (relayConnection) {
+        relayConnection.endSession(reason);
+        relayConnection.destroy();
+        activeRelayConnections.delete(callSessionId);
+      }
+
+      // Clean up orchestrator
+      const orchestrator = getCallOrchestrator(callSessionId);
+      if (orchestrator) {
+        orchestrator.destroy();
+        unregisterCallOrchestrator(callSessionId);
+      }
+
+      // Update session status
+      updateCallSession(callSessionId, {
+        status: 'completed',
+        endedAt: Date.now(),
+      });
+
+      log.info({ callSessionId }, 'Call ended successfully');
+
+      const lines = [
+        'Call ended successfully.',
+        `  Call Session ID: ${callSessionId}`,
+        `  Status: completed`,
+      ];
+      if (reason) {
+        lines.push(`  Reason: ${reason}`);
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error({ err, callSessionId }, 'Failed to end call');
+      return { content: `Error ending call: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new CallEndTool());

package/src/tools/calls/call-start.ts

@@ -0,0 +1,134 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { DENIED_NUMBERS } from '../../calls/call-constants.js';
+import { createCallSession, updateCallSession } from '../../calls/call-store.js';
+import { TwilioConversationRelayProvider } from '../../calls/twilio-provider.js';
+import { getTwilioConfig } from '../../calls/twilio-config.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('call-start');
+
+const E164_REGEX = /^\+\d+$/;
+
+const definition: ToolDefinition = {
+  name: 'call_start',
+  description:
+    'Place an outbound phone call via AI voice. The assistant will converse with the callee on behalf of the user.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      phone_number: {
+        type: 'string',
+        description: 'E.164 formatted phone number (e.g. +14155551234)',
+      },
+      task: {
+        type: 'string',
+        description: 'What the call should accomplish',
+      },
+      context: {
+        type: 'string',
+        description: 'Additional context for the conversation',
+      },
+    },
+    required: ['phone_number', 'task'],
+  },
+};
+
+class CallStartTool implements Tool {
+  name = 'call_start';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.High;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const phoneNumber = input.phone_number as string | undefined;
+    if (!phoneNumber || typeof phoneNumber !== 'string') {
+      return { content: 'Error: phone_number is required and must be a string', isError: true };
+    }
+
+    if (!E164_REGEX.test(phoneNumber)) {
+      return {
+        content: 'Error: phone_number must be in E.164 format (starts with + followed by digits, e.g. +14155551234)',
+        isError: true,
+      };
+    }
+
+    const task = input.task as string | undefined;
+    if (!task || typeof task !== 'string' || task.trim().length === 0) {
+      return { content: 'Error: task is required and must be a non-empty string', isError: true };
+    }
+
+    if (DENIED_NUMBERS.has(phoneNumber)) {
+      return { content: 'Error: this phone number is not allowed to be called', isError: true };
+    }
+
+    const callContext = input.context as string | undefined;
+
+    // Create session outside the try block so it's available in the catch block
+    // for marking as failed if the provider call fails.
+    let sessionId: string | null = null;
+
+    try {
+      const config = getTwilioConfig();
+      const provider = new TwilioConversationRelayProvider();
+
+      const session = createCallSession({
+        conversationId: context.conversationId,
+        provider: 'twilio',
+        fromNumber: config.phoneNumber,
+        toNumber: phoneNumber,
+        task: callContext ? `${task}\n\nContext: ${callContext}` : task,
+      });
+      sessionId = session.id;
+
+      log.info({ callSessionId: session.id, to: phoneNumber, task }, 'Initiating outbound call');
+
+      const baseUrl = config.webhookBaseUrl.replace(/\/$/, '');
+      const { callSid } = await provider.initiateCall({
+        from: config.phoneNumber,
+        to: phoneNumber,
+        webhookUrl: `${baseUrl}/v1/calls/twilio/voice-webhook?callSessionId=${session.id}`,
+        statusCallbackUrl: `${baseUrl}/v1/calls/twilio/status`,
+      });
+
+      updateCallSession(session.id, { providerCallSid: callSid });
+
+      log.info({ callSessionId: session.id, callSid }, 'Call initiated successfully');
+
+      return {
+        content: [
+          'Call initiated successfully.',
+          `  Call Session ID: ${session.id}`,
+          `  Call SID: ${callSid}`,
+          `  To: ${phoneNumber}`,
+          `  Status: initiated`,
+          '',
+          'The AI voice assistant is now placing the call. Use call_status to check progress.',
+        ].join('\n'),
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error({ err, phoneNumber }, 'Failed to initiate call');
+
+      // Mark the session as failed so it doesn't stay in 'initiated' state
+      if (sessionId) {
+        updateCallSession(sessionId, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: msg,
+        });
+      }
+
+      return { content: `Error initiating call: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new CallStartTool());

package/src/tools/calls/call-status.ts

@@ -0,0 +1,97 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { getCallSession, getActiveCallSessionForConversation, getPendingQuestion } from '../../calls/call-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('call-status');
+
+const definition: ToolDefinition = {
+  name: 'call_status',
+  description: 'Check the status of an active or recent phone call',
+  input_schema: {
+    type: 'object',
+    properties: {
+      call_session_id: {
+        type: 'string',
+        description: 'Specific call session ID to check. If omitted, checks for an active call in the current conversation.',
+      },
+    },
+    required: [],
+  },
+};
+
+class CallStatusTool implements Tool {
+  name = 'call_status';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const callSessionId = input.call_session_id as string | undefined;
+
+    try {
+      let session;
+
+      if (callSessionId) {
+        session = getCallSession(callSessionId);
+        if (!session) {
+          return { content: `Error: no call session found with ID ${callSessionId}`, isError: true };
+        }
+      } else {
+        session = getActiveCallSessionForConversation(context.conversationId);
+        if (!session) {
+          return { content: 'No active call found in the current conversation.', isError: false };
+        }
+      }
+
+      log.info({ callSessionId: session.id, status: session.status }, 'Checking call status');
+
+      const lines = [
+        `Call Session: ${session.id}`,
+        `  Status: ${session.status}`,
+        `  To: ${session.toNumber}`,
+        `  From: ${session.fromNumber}`,
+      ];
+
+      if (session.providerCallSid) {
+        lines.push(`  Call SID: ${session.providerCallSid}`);
+      }
+
+      if (session.task) {
+        lines.push(`  Task: ${session.task}`);
+      }
+
+      if (session.startedAt) {
+        const durationMs = (session.endedAt ?? Date.now()) - session.startedAt;
+        const durationSec = Math.round(durationMs / 1000);
+        lines.push(`  Duration: ${durationSec}s`);
+      }
+
+      if (session.lastError) {
+        lines.push(`  Last Error: ${session.lastError}`);
+      }
+
+      // Check for pending questions from the call
+      const pendingQuestion = getPendingQuestion(session.id);
+      if (pendingQuestion) {
+        lines.push('');
+        lines.push(`  Pending Question: ${pendingQuestion.questionText}`);
+        lines.push(`  Question ID: ${pendingQuestion.id}`);
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error({ err, callSessionId }, 'Failed to check call status');
+      return { content: `Error checking call status: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new CallStatusTool());

package/src/tools/credentials/vault.ts

@@ -113,7 +113,7 @@ class CredentialStoreTool implements Tool {
   name = 'credential_store';
   description = 'Store, list, delete, or prompt for credentials in the secure vault';
   category = 'credentials';
-  defaultRiskLevel = RiskLevel.Medium;
+  defaultRiskLevel = RiskLevel.Low;
 
   getDefinition(): ToolDefinition {
     return {

package/src/tools/registry.ts

@@ -198,7 +198,7 @@ export function getAllToolDefinitions(): ToolDefinition[] {
 }
 
 export async function initializeTools(): Promise<void> {
-  const { eagerModules, eagerModuleToolNames, explicitTools, lazyTools } = await import('./tool-manifest.js');
+  const { loadEagerModules, eagerModuleToolNames, explicitTools, lazyTools } = await import('./tool-manifest.js');
 
   // Capture tool names already in the registry before any manifest
   // registrations.  In production this is empty; in tests a non-skill tool
@@ -206,9 +206,7 @@ export async function initializeTools(): Promise<void> {
   const preExisting = new Set(tools.keys());
 
   // Import tool modules to trigger registration side effects.
-  for (const modulePath of eagerModules) {
-    await import(modulePath);
-  }
+  await loadEagerModules();
 
   // Explicit tool instances — no side-effect import required.
   for (const tool of explicitTools) {

package/src/tools/tasks/index.ts

@@ -23,3 +23,5 @@ export { taskListTool } from './task-list.js';
 export { taskDeleteTool } from './task-delete.js';
 export { taskListShowTool } from './work-item-list.js';
 export { taskListAddTool } from './work-item-enqueue.js';
+export { taskListUpdateTool } from './work-item-update.js';
+export { taskListRemoveTool } from './work-item-remove.js';

package/src/tools/tasks/task-delete.ts

@@ -2,6 +2,10 @@ import { RiskLevel } from '../../permissions/types.js';
 import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 import type { ToolDefinition } from '../../providers/types.js';
 import { deleteTask, deleteTasks, getTask } from '../../tasks/task-store.js';
+import { removeWorkItemFromQueue } from '../../work-items/work-item-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-delete');
 
 const definition: ToolDefinition = {
   name: 'task_delete',
@@ -44,23 +48,60 @@ class TaskDeleteTool implements Tool {
         const task = getTask(ids[0]);
         const deleted = deleteTask(ids[0]);
         if (!deleted) {
-          return { content: `No task found with ID ${ids[0]}`, isError: true };
+          // The LLM may pass a work item ID instead of a task template ID.
+          // Fall back to removing from the task queue so the user's intent succeeds.
+          const result = removeWorkItemFromQueue(ids[0]);
+          if (result.success) {
+            log.info({ inputId: ids[0], fallback: true, deletedCount: 1 }, 'deleted via work item fallback');
+            return { content: result.message, isError: false };
+          }
+          log.warn({ inputId: ids[0] }, 'no task or work item found for deletion');
+          return { content: `No task template or work item found with ID "${ids[0]}". Use task_list to see task templates or task_list_show to see work items in the queue.`, isError: true };
         }
+        log.info({ taskId: ids[0], title: task?.title, deletedCount: 1 }, 'task deleted');
         return { content: `Deleted task: ${task?.title ?? ids[0]}`, isError: false };
       }
 
-      const titles = ids.map((id) => {
-        const t = getTask(id);
-        return t ? t.title : id;
-      });
-      const count = deleteTasks(ids);
-      if (count === 0) {
+      const taskIds: string[] = [];
+      const taskTitles: string[] = [];
+      const workItemTitles: string[] = [];
+
+      for (const id of ids) {
+        const task = getTask(id);
+        if (task) {
+          taskIds.push(id);
+          taskTitles.push(task.title);
+        } else {
+          const result = removeWorkItemFromQueue(id);
+          if (result.success) {
+            log.info({ inputId: id, fallback: true }, 'deleted work item in batch (fallback)');
+            workItemTitles.push(result.title);
+          } else {
+            log.warn({ inputId: id }, 'batch delete: no task or work item found');
+          }
+        }
+      }
+
+      const taskCount = taskIds.length > 0 ? deleteTasks(taskIds) : 0;
+
+      if (taskCount === 0 && workItemTitles.length === 0) {
+        log.warn({ inputIds: ids }, 'no matching tasks found to delete');
         return { content: 'No matching tasks found to delete.', isError: true };
       }
-      const lines = [`Deleted ${count} task(s):`, ...titles.map((t) => `- ${t}`)];
+
+      log.info({ deletedTasks: taskCount, deletedWorkItems: workItemTitles.length, totalInput: ids.length }, 'batch delete completed');
+
+      const lines: string[] = [];
+      if (taskCount > 0) {
+        lines.push(`Deleted ${taskCount} task(s):`, ...taskTitles.map((t) => `- ${t}`));
+      }
+      if (workItemTitles.length > 0) {
+        lines.push(`Removed ${workItemTitles.length} item(s) from the task queue:`, ...workItemTitles.map((t) => `- ${t}`));
+      }
       return { content: lines.join('\n'), isError: false };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
+      log.error({ inputIds: ids, error: msg }, 'delete failed');
       return { content: `Error: ${msg}`, isError: true };
     }
   }

package/src/tools/tasks/task-run.ts

@@ -3,6 +3,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 import type { ToolDefinition } from '../../providers/types.js';
 import { getTask, listTasks } from '../../tasks/task-store.js';
 import { renderTemplate } from '../../tasks/task-runner.js';
+import { identifyEntityById, buildWorkItemMismatchError } from '../../work-items/work-item-store.js';
 
 const definition: ToolDefinition = {
   name: 'task_run',
@@ -57,7 +58,14 @@ class TaskRunTool implements Tool {
       if (taskId) {
         task = getTask(taskId);
         if (!task) {
-          return { content: `Error: No task found with ID "${taskId}"`, isError: true };
+          const entity = identifyEntityById(taskId);
+          if (entity.type === 'work_item') {
+            return {
+              content: `Error: ${buildWorkItemMismatchError(taskId, entity.title!, 'task_list_show to view work items, or task_list_update to modify them')}`,
+              isError: true,
+            };
+          }
+          return { content: `Error: No task template found with ID "${taskId}". Use task_list to see available templates.`, isError: true };
         }
       } else if (taskName) {
         const allTasks = listTasks();