vellum 0.0.16 → 0.2.0

package/src/tools/computer-use/request-computer-control.ts

@@ -0,0 +1,53 @@
+/**
+ * computer_use_request_control tool definition.
+ *
+ * This tool allows a text_qa session to escalate to foreground computer use
+ * when the user explicitly requests it (e.g. "go ahead and do it", "take over
+ * for 20 seconds"). It is a proxy tool — execution is handled by the session's
+ * surfaceProxyResolver, which creates a CU session and sends a task_routed
+ * message to the client.
+ *
+ * This tool is only available to text_qa sessions. It must NOT be added to
+ * CU sessions (that would be recursive).
+ *
+ * Part of the bundled computer-use skill. The definition here is imported by
+ * buildToolDefinitions() so text_qa sessions can include it without
+ * preactivating the entire skill.
+ */
+
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+
+export const requestComputerControlTool: Tool = {
+  name: 'computer_use_request_control',
+  description:
+    'Escalate to foreground computer use. Call this when the user explicitly asks you to ' +
+    'take control of their computer to perform a task (e.g. "go ahead and do it", ' +
+    '"take over", "open that for me"). Provide a concise description of the task ' +
+    'that computer use should accomplish.',
+  category: 'computer-use',
+  defaultRiskLevel: RiskLevel.Low,
+  executionMode: 'proxy',
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          task: {
+            type: 'string',
+            description: 'Concise description of what computer use should accomplish',
+          },
+        },
+        required: ['task'],
+      },
+    };
+  },
+
+  execute(): Promise<ToolExecutionResult> {
+    throw new Error('Proxy tool: execution must be forwarded via surfaceProxyResolver');
+  },
+};

package/src/tools/computer-use/skill-proxy-bridge.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared helper for computer-use skill wrapper scripts.
+ *
+ * Each wrapper calls forwardComputerUseProxyTool() to delegate execution to
+ * the proxy resolver, which forwards the call to the connected macOS client.
+ */
+
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+
+/**
+ * Forward a computer-use proxy tool call through the context's proxyToolResolver.
+ *
+ * Returns a clear error result if the resolver is missing (e.g. when the tool
+ * is invoked outside a session with a connected client).
+ */
+export function forwardComputerUseProxyTool(
+  toolName: string,
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  if (!context.proxyToolResolver) {
+    return Promise.resolve({
+      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected macOS client.`,
+      isError: true,
+    });
+  }
+  return context.proxyToolResolver(toolName, input);
+}

package/src/tools/contacts/contact-merge.ts

@@ -0,0 +1,87 @@
+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 { mergeContacts, getContact } from '../../contacts/contact-store.js';
+
+const definition: ToolDefinition = {
+  name: 'contact_merge',
+  description: 'Merge two contacts when you discover they are the same person (e.g. same person on email and Slack). Combines channels, keeps the higher importance, and deletes the donor contact.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      keep_id: {
+        type: 'string',
+        description: 'ID of the contact to keep (the surviving contact)',
+      },
+      merge_id: {
+        type: 'string',
+        description: 'ID of the contact to merge into the kept contact (will be deleted)',
+      },
+    },
+    required: ['keep_id', 'merge_id'],
+  },
+};
+
+class ContactMergeTool implements Tool {
+  name = 'contact_merge';
+  description = definition.description;
+  category = 'contacts';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const keepId = input.keep_id as string | undefined;
+    const mergeId = input.merge_id as string | undefined;
+
+    if (!keepId || typeof keepId !== 'string') {
+      return { content: 'Error: keep_id is required', isError: true };
+    }
+    if (!mergeId || typeof mergeId !== 'string') {
+      return { content: 'Error: merge_id is required', isError: true };
+    }
+
+    // Show what will be merged for clarity
+    const keepContact = getContact(keepId);
+    const mergeContact = getContact(mergeId);
+
+    if (!keepContact) {
+      return { content: `Error: Contact "${keepId}" not found`, isError: true };
+    }
+    if (!mergeContact) {
+      return { content: `Error: Contact "${mergeId}" not found`, isError: true };
+    }
+
+    try {
+      const merged = mergeContacts(keepId, mergeId);
+
+      const channelList = merged.channels
+        .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
+        .join('\n');
+
+      return {
+        content: [
+          `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
+          ``,
+          `Surviving contact (${merged.id}):`,
+          `  Name: ${merged.displayName}`,
+          `  Importance: ${merged.importance.toFixed(2)}`,
+          `  Interactions: ${merged.interactionCount}`,
+          merged.relationship ? `  Relationship: ${merged.relationship}` : null,
+          merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+          ``,
+          `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
+        ].filter(Boolean).join('\n'),
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new ContactMergeTool());

package/src/tools/contacts/contact-search.ts

@@ -0,0 +1,102 @@
+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 { searchContacts } from '../../contacts/contact-store.js';
+import type { ContactWithChannels } from '../../contacts/types.js';
+
+function formatContactSummary(c: ContactWithChannels): string {
+  const parts = [`- **${c.displayName}** (ID: ${c.id})`];
+  if (c.relationship) parts.push(`  Relationship: ${c.relationship}`);
+  parts.push(`  Importance: ${c.importance.toFixed(2)} | Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    const channelList = c.channels
+      .map((ch) => `${ch.type}:${ch.address}${ch.isPrimary ? '*' : ''}`)
+      .join(', ');
+    parts.push(`  Channels: ${channelList}`);
+  }
+  return parts.join('\n');
+}
+
+const definition: ToolDefinition = {
+  name: 'contact_search',
+  description: 'Search for contacts by name, channel address, relationship type, or other criteria. Returns matching contacts with their channel information.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search by display name (partial match)',
+      },
+      channel_address: {
+        type: 'string',
+        description: 'Search by channel address (email, phone, handle — partial match)',
+      },
+      channel_type: {
+        type: 'string',
+        description: 'Filter by channel type when searching by address (email, slack, whatsapp, phone, etc.)',
+      },
+      relationship: {
+        type: 'string',
+        description: 'Filter by relationship type (exact match)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum results to return (default 20, max 100)',
+      },
+    },
+    required: [],
+  },
+};
+
+class ContactSearchTool implements Tool {
+  name = 'contact_search';
+  description = definition.description;
+  category = 'contacts';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const query = input.query as string | undefined;
+    const channelAddress = input.channel_address as string | undefined;
+    const channelType = input.channel_type as string | undefined;
+    const relationship = input.relationship as string | undefined;
+    const limit = input.limit as number | undefined;
+
+    if (!query && !channelAddress && !relationship) {
+      return {
+        content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
+        isError: true,
+      };
+    }
+
+    try {
+      const results = searchContacts({
+        query,
+        channelAddress,
+        channelType,
+        relationship,
+        limit,
+      });
+
+      if (results.length === 0) {
+        return { content: 'No contacts found matching the search criteria.', isError: false };
+      }
+
+      const lines = [`Found ${results.length} contact(s):\n`];
+      for (const contact of results) {
+        lines.push(formatContactSummary(contact));
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new ContactSearchTool());

package/src/tools/contacts/contact-upsert.ts

@@ -0,0 +1,137 @@
+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 { upsertContact } from '../../contacts/contact-store.js';
+import { CHANNEL_TYPES } from '../../contacts/types.js';
+
+function formatContact(c: ReturnType<typeof upsertContact>): string {
+  const lines = [
+    `Contact ${c.id}`,
+    `  Name: ${c.displayName}`,
+  ];
+  if (c.relationship) lines.push(`  Relationship: ${c.relationship}`);
+  lines.push(`  Importance: ${c.importance.toFixed(2)}`);
+  if (c.responseExpectation) lines.push(`  Response expectation: ${c.responseExpectation}`);
+  if (c.preferredTone) lines.push(`  Preferred tone: ${c.preferredTone}`);
+  if (c.interactionCount > 0) lines.push(`  Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    lines.push('  Channels:');
+    for (const ch of c.channels) {
+      const primary = ch.isPrimary ? ' (primary)' : '';
+      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+const definition: ToolDefinition = {
+  name: 'contact_upsert',
+  description: 'Create or update a contact in the relationship graph. Use this to track people the user interacts with across channels (email, Slack, etc.).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      id: {
+        type: 'string',
+        description: 'Contact ID to update. Omit to create a new contact (or auto-match by channel address).',
+      },
+      display_name: {
+        type: 'string',
+        description: 'Display name for the contact',
+      },
+      relationship: {
+        type: 'string',
+        description: 'Relationship type (e.g. colleague, friend, manager, client, family)',
+      },
+      importance: {
+        type: 'number',
+        description: 'Importance score 0-1 (default 0.5). Higher = more important.',
+      },
+      response_expectation: {
+        type: 'string',
+        description: 'Expected response speed (e.g. immediate, within_hours, within_day, casual)',
+      },
+      preferred_tone: {
+        type: 'string',
+        description: 'Preferred communication tone (e.g. formal, casual, friendly, professional)',
+      },
+      channels: {
+        type: 'array',
+        description: 'Communication channels for this contact',
+        items: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: [...CHANNEL_TYPES],
+              description: 'Channel type',
+            },
+            address: {
+              type: 'string',
+              description: 'Channel address (email address, Slack handle, phone number, etc.)',
+            },
+            is_primary: {
+              type: 'boolean',
+              description: 'Whether this is the primary channel for this type',
+            },
+          },
+          required: ['type', 'address'],
+        },
+      },
+    },
+    required: ['display_name'],
+  },
+};
+
+class ContactUpsertTool implements Tool {
+  name = 'contact_upsert';
+  description = definition.description;
+  category = 'contacts';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const displayName = input.display_name as string | undefined;
+    if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
+      return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
+    }
+
+    const importance = input.importance as number | undefined;
+    if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
+      return { content: 'Error: importance must be a number between 0 and 1', isError: true };
+    }
+
+    const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
+    const channels = rawChannels?.map((ch) => ({
+      type: ch.type,
+      address: ch.address,
+      isPrimary: ch.is_primary,
+    }));
+
+    try {
+      const contact = upsertContact({
+        id: input.id as string | undefined,
+        displayName: displayName.trim(),
+        relationship: input.relationship as string | undefined,
+        importance,
+        responseExpectation: input.response_expectation as string | undefined,
+        preferredTone: input.preferred_tone as string | undefined,
+        channels,
+      });
+
+      const isNew = contact.createdAt === contact.updatedAt;
+      return {
+        content: `${isNew ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new ContactUpsertTool());

package/src/tools/contacts/index.ts

@@ -0,0 +1,4 @@
+// Side-effect imports — each module calls registerTool() at the top level.
+import './contact-upsert.js';
+import './contact-search.js';
+import './contact-merge.js';

package/src/tools/credentials/account-registry.ts

@@ -0,0 +1,127 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import {
+  createAccount,
+  listAccounts,
+  getAccount,
+  updateAccount,
+} from '../../memory/account-store.js';
+
+class AccountManageTool implements Tool {
+  name = 'account_manage';
+  description = 'Create, list, get, or update account records';
+  category = 'credentials';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['create', 'list', 'get', 'update'],
+            description: 'CRUD operation',
+          },
+          id: {
+            type: 'string',
+            description: 'Account ID (for get/update)',
+          },
+          service: {
+            type: 'string',
+            description: 'Service name',
+          },
+          username: { type: 'string' },
+          email: { type: 'string' },
+          display_name: { type: 'string' },
+          status: {
+            type: 'string',
+            enum: ['active', 'pending_verification', 'suspended'],
+          },
+          credential_ref: {
+            type: 'string',
+            description: 'Service name linking to credential vault',
+          },
+          metadata: { type: 'object' },
+        },
+        required: ['action'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const action = input.action as string;
+
+    switch (action) {
+      case 'create': {
+        const service = input.service as string | undefined;
+        if (!service || typeof service !== 'string') {
+          return { content: 'Error: service is required for create action', isError: true };
+        }
+
+        const record = createAccount({
+          service,
+          username: input.username as string | undefined,
+          email: input.email as string | undefined,
+          displayName: input.display_name as string | undefined,
+          status: input.status as string | undefined,
+          credentialRef: input.credential_ref as string | undefined,
+          metadata: input.metadata as Record<string, unknown> | undefined,
+        });
+
+        return { content: JSON.stringify(record, null, 2), isError: false };
+      }
+
+      case 'list': {
+        const records = listAccounts({
+          service: input.service as string | undefined,
+          status: input.status as string | undefined,
+        });
+        return { content: JSON.stringify(records, null, 2), isError: false };
+      }
+
+      case 'get': {
+        const id = input.id as string | undefined;
+        if (!id || typeof id !== 'string') {
+          return { content: 'Error: id is required for get action', isError: true };
+        }
+
+        const record = getAccount(id);
+        if (!record) {
+          return { content: `Error: account not found: ${id}`, isError: true };
+        }
+        return { content: JSON.stringify(record, null, 2), isError: false };
+      }
+
+      case 'update': {
+        const id = input.id as string | undefined;
+        if (!id || typeof id !== 'string') {
+          return { content: 'Error: id is required for update action', isError: true };
+        }
+
+        const updated = updateAccount(id, {
+          service: input.service as string | undefined,
+          username: input.username as string | undefined,
+          email: input.email as string | undefined,
+          displayName: input.display_name as string | undefined,
+          status: input.status as string | undefined,
+          credentialRef: input.credential_ref as string | undefined,
+          metadata: input.metadata as Record<string, unknown> | undefined,
+        });
+
+        if (!updated) {
+          return { content: `Error: account not found: ${id}`, isError: true };
+        }
+        return { content: JSON.stringify(updated, null, 2), isError: false };
+      }
+
+      default:
+        return { content: `Error: unknown action "${action}"`, isError: true };
+    }
+  }
+}
+
+export const accountManageTool = new AccountManageTool();

package/src/tools/credentials/broker-types.ts

@@ -0,0 +1,107 @@
+/** Opaque token representing a policy-checked authorization to use a credential. */
+export interface UsageToken {
+  tokenId: string;
+  credentialId: string;
+  service: string;
+  field: string;
+  toolName: string;
+  /** Timestamp (epoch ms) when this token was created. */
+  createdAt: number;
+  /** Whether this token has been consumed (single-use). */
+  consumed: boolean;
+}
+
+/** Request to authorize the use of a credential. */
+export interface AuthorizeRequest {
+  service: string;
+  field: string;
+  toolName: string;
+  /** Optional domain for domain-policy checking (used by browser tools). */
+  domain?: string;
+}
+
+/** Successful authorization result. */
+export interface AuthorizeSuccess {
+  authorized: true;
+  token: UsageToken;
+}
+
+/** Denied authorization result. */
+export interface AuthorizeDenied {
+  authorized: false;
+  reason: string;
+}
+
+export type AuthorizeResult = AuthorizeSuccess | AuthorizeDenied;
+
+/** Result of consuming a token. */
+export interface ConsumeResult {
+  success: boolean;
+  /** The storage key to read the secret from (only present on success). */
+  storageKey?: string;
+  /** The resolved value when a transient (one-time) credential was consumed. */
+  value?: string;
+  /** Error reason if consumption failed. */
+  reason?: string;
+}
+
+/** Request for the broker to fill a browser field without exposing plaintext. */
+export interface BrowserFillRequest {
+  service: string;
+  field: string;
+  toolName: string;
+  domain?: string;
+  /**
+   * Opaque fill callback — the broker calls this with the plaintext value internally.
+   * The caller provides the fill function but never receives the secret value.
+   */
+  fill: (value: string) => Promise<void>;
+}
+
+/** Result of a broker-mediated browser fill — contains only metadata, never plaintext. */
+export interface BrowserFillResult {
+  success: boolean;
+  reason?: string;
+}
+
+/** Request for the broker to use a credential server-side without exposing plaintext. */
+export interface ServerUseRequest<T> {
+  service: string;
+  field: string;
+  toolName: string;
+  /**
+   * Opaque callback — the broker calls this with the plaintext value internally.
+   * The caller provides the function but never receives the secret value directly.
+   */
+  execute: (value: string) => Promise<T>;
+}
+
+/** Result of a broker-mediated server-side credential use — contains the callback result, never plaintext. */
+export interface ServerUseResult<T> {
+  success: boolean;
+  result?: T;
+  reason?: string;
+}
+
+/** Request to look up a credential by ID for proxy injection (no secret exposed). */
+export interface ServerUseByIdRequest {
+  credentialId: string;
+  requestingTool: string;
+}
+
+/** Successful by-id lookup result — metadata + injection templates, never plaintext. */
+export interface ServerUseByIdSuccess {
+  success: true;
+  credentialId: string;
+  service: string;
+  field: string;
+  injectionTemplates: import('./policy-types.js').CredentialInjectionTemplate[];
+}
+
+/** Denied or not-found by-id lookup result. */
+export interface ServerUseByIdDenied {
+  success: false;
+  reason: string;
+}
+
+export type ServerUseByIdResult = ServerUseByIdSuccess | ServerUseByIdDenied;