vellum 0.0.16 → 0.2.0

package/src/tools/apps/definitions.ts

@@ -0,0 +1,59 @@
+/**
+ * Core app proxy tool definitions.
+ *
+ * Only the `app_open` proxy tool remains here -- it is forwarded to the
+ * connected macOS client (same pattern as ui_show).  All non-proxy data
+ * tools (create, list, query, update, delete, file ops) are now provided
+ * by the bundled app-builder skill via its TOOLS.json manifest and
+ * executor scripts.
+ */
+
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function proxyExecute(): Promise<ToolExecutionResult> {
+  throw new Error('Proxy tool: execution must be forwarded to the connected client');
+}
+
+// ---------------------------------------------------------------------------
+// app_open
+// ---------------------------------------------------------------------------
+
+const appOpenTool: Tool = {
+  name: 'app_open',
+  description:
+    'Open a persistent app in a dynamic_page surface on the connected client.',
+  category: 'apps',
+  defaultRiskLevel: RiskLevel.Low,
+  executionMode: 'proxy',
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          app_id: {
+            type: 'string',
+            description: 'The ID of the app to open',
+          },
+        },
+        required: ['app_id'],
+      },
+    };
+  },
+
+  execute: proxyExecute,
+};
+
+// ---------------------------------------------------------------------------
+// Proxy-only tools registered in the core daemon registry
+// ---------------------------------------------------------------------------
+
+export const coreAppProxyTools: Tool[] = [appOpenTool];

package/src/tools/apps/executors.ts

@@ -0,0 +1,313 @@
+/**
+ * Standalone executor functions for app tool operations.
+ *
+ * Each executor encapsulates the business logic that was previously inline
+ * in the tool definition's execute() handler.  They accept plain typed
+ * parameters and return plain result objects, making them reusable from
+ * both core tool handlers and skill scripts without depending on
+ * ToolDefinition or ToolContext types.
+ */
+
+import type { AppDefinition } from '../../memory/app-store.js';
+import type { EditEngineResult } from '../../memory/app-store.js';
+import { setHomeBaseAppLink } from '../../home-base/app-link-store.js';
+import { openAppViaSurface } from './open-proxy.js';
+
+// ---------------------------------------------------------------------------
+// Shared result type
+// ---------------------------------------------------------------------------
+
+export interface ExecutorResult {
+  content: string;
+  isError: boolean;
+  /** Optional status message for display (e.g. progress indicator). */
+  status?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Dependency interfaces — callers inject these rather than importing the
+// app-store module directly, which makes the executors testable with mocks.
+// ---------------------------------------------------------------------------
+
+export interface AppStoreReader {
+  getApp(id: string): AppDefinition | null;
+  listApps(): AppDefinition[];
+  queryAppRecords(appId: string): unknown[];
+  listAppFiles(appId: string): string[];
+  readAppFile(appId: string, path: string): string;
+}
+
+export interface AppStoreWriter {
+  createApp(params: {
+    name: string;
+    description?: string;
+    schemaJson: string;
+    htmlDefinition: string;
+    pages?: Record<string, string>;
+    appType?: 'app' | 'site';
+  }): AppDefinition;
+  updateApp(
+    id: string,
+    updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>>,
+  ): AppDefinition;
+  deleteApp(id: string): void;
+  writeAppFile(appId: string, path: string, content: string): void;
+  editAppFile(
+    appId: string,
+    path: string,
+    oldString: string,
+    newString: string,
+    replaceAll?: boolean,
+  ): EditEngineResult;
+}
+
+export type AppStore = AppStoreReader & AppStoreWriter;
+
+/**
+ * Proxy resolver type matching the shape used by the core tool context.
+ * Allows app_create's auto-open behavior to forward to the connected client.
+ */
+export type ProxyResolver = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ExecutorResult>;
+
+// ---------------------------------------------------------------------------
+// app_create
+// ---------------------------------------------------------------------------
+
+export interface AppCreateInput {
+  name: string;
+  description?: string;
+  schema_json?: string;
+  html: string;
+  pages?: Record<string, string>;
+  type?: 'app' | 'site';
+  auto_open?: boolean;
+  set_as_home_base?: boolean;
+  preview?: Record<string, unknown>;
+}
+
+export async function executeAppCreate(
+  input: AppCreateInput,
+  store: AppStore,
+  proxyToolResolver?: ProxyResolver,
+): Promise<ExecutorResult> {
+  const name = input.name;
+  const description = input.description;
+  const schemaJson = input.schema_json ?? '{}';
+  const htmlDefinition = input.html;
+  const pages = input.pages;
+  const autoOpen = input.auto_open !== false; // default true
+  const preview = input.preview;
+  const appType = input.type === 'site' ? 'site' as const : 'app' as const;
+
+  const app = store.createApp({ name, description, schemaJson, htmlDefinition, pages, appType });
+
+  if (input.set_as_home_base) {
+    setHomeBaseAppLink(app.id, 'personalized');
+  }
+
+  // Auto-open the app via the shared open-proxy helper
+  if (autoOpen && proxyToolResolver) {
+    const extraInput = preview ? { preview } : undefined;
+    const openResultText = await openAppViaSurface(app.id, proxyToolResolver, extraInput);
+
+    // Determine whether the open succeeded by checking for the fallback text
+    const opened = openResultText !== 'Failed to auto-open app. Use app_open to open it manually.';
+    if (opened) {
+      return {
+        content: JSON.stringify({
+          ...app,
+          auto_opened: true,
+          open_result: openResultText,
+        }),
+        isError: false,
+      };
+    }
+
+    return {
+      content: JSON.stringify({
+        ...app,
+        auto_opened: false,
+        auto_open_error: openResultText,
+      }),
+      isError: false,
+    };
+  }
+
+  return { content: JSON.stringify(app), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_list
+// ---------------------------------------------------------------------------
+
+export function executeAppList(store: AppStoreReader): ExecutorResult {
+  const apps = store.listApps().map((a) => ({
+    id: a.id,
+    name: a.name,
+    description: a.description,
+    updatedAt: a.updatedAt,
+  }));
+  return { content: JSON.stringify(apps), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_query
+// ---------------------------------------------------------------------------
+
+export interface AppQueryInput {
+  app_id: string;
+}
+
+export function executeAppQuery(
+  input: AppQueryInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const records = store.queryAppRecords(input.app_id);
+  return { content: JSON.stringify(records), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_update
+// ---------------------------------------------------------------------------
+
+export interface AppUpdateInput {
+  app_id: string;
+  name?: string;
+  description?: string;
+  schema_json?: string;
+  html?: string;
+  pages?: Record<string, string>;
+}
+
+export function executeAppUpdate(
+  input: AppUpdateInput,
+  store: AppStore,
+): ExecutorResult {
+  const updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>> = {};
+  if (typeof input.name === 'string') updates.name = input.name;
+  if (typeof input.description === 'string') updates.description = input.description;
+  if (typeof input.schema_json === 'string') updates.schemaJson = input.schema_json;
+  if (typeof input.html === 'string') updates.htmlDefinition = input.html;
+  if (input.pages && typeof input.pages === 'object') updates.pages = input.pages;
+
+  const app = store.updateApp(input.app_id, updates);
+  return { content: JSON.stringify(app), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_delete
+// ---------------------------------------------------------------------------
+
+export interface AppDeleteInput {
+  app_id: string;
+}
+
+export function executeAppDelete(
+  input: AppDeleteInput,
+  store: AppStore,
+): ExecutorResult {
+  store.deleteApp(input.app_id);
+  return { content: JSON.stringify({ deleted: true, appId: input.app_id }), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_list
+// ---------------------------------------------------------------------------
+
+export interface AppFileListInput {
+  app_id: string;
+}
+
+export function executeAppFileList(
+  input: AppFileListInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const files = store.listAppFiles(input.app_id);
+  return { content: JSON.stringify(files), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_read
+// ---------------------------------------------------------------------------
+
+export interface AppFileReadInput {
+  app_id: string;
+  path: string;
+  offset?: number;
+  limit?: number;
+}
+
+export function executeAppFileRead(
+  input: AppFileReadInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const offset = input.offset ?? 1;
+  const limit = input.limit;
+
+  const raw = store.readAppFile(input.app_id, input.path);
+  const allLines = raw.split('\n');
+  const startIndex = Math.max(0, offset - 1);
+  const sliced = limit != null ? allLines.slice(startIndex, startIndex + limit) : allLines.slice(startIndex);
+
+  const formatted = sliced
+    .map((line, i) => {
+      const lineNum = startIndex + i + 1;
+      return `${String(lineNum).padStart(6)}\t${line}`;
+    })
+    .join('\n');
+
+  return { content: formatted, isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_edit
+// ---------------------------------------------------------------------------
+
+export interface AppFileEditInput {
+  app_id: string;
+  path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+  status?: string;
+}
+
+export function executeAppFileEdit(
+  input: AppFileEditInput,
+  store: AppStore,
+): ExecutorResult {
+  if (!input.old_string) {
+    return { content: JSON.stringify({ error: 'old_string must not be empty' }), isError: true };
+  }
+
+  const replaceAll = input.replace_all ?? false;
+  const result = store.editAppFile(input.app_id, input.path, input.old_string, input.new_string, replaceAll);
+  return { content: JSON.stringify(result), isError: false, status: input.status };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_write
+// ---------------------------------------------------------------------------
+
+export interface AppFileWriteInput {
+  app_id: string;
+  path: string;
+  content: string;
+  status?: string;
+}
+
+export function executeAppFileWrite(
+  input: AppFileWriteInput,
+  store: AppStore,
+): ExecutorResult {
+  const app = store.getApp(input.app_id);
+  if (!app) {
+    return { content: JSON.stringify({ error: `App '${input.app_id}' not found` }), isError: true };
+  }
+
+  store.writeAppFile(input.app_id, input.path, input.content);
+  return { content: JSON.stringify({ written: true, path: input.path }), isError: false, status: input.status };
+}

package/src/tools/apps/open-proxy.ts

@@ -0,0 +1,43 @@
+/**
+ * Centralized helper for resolving and executing the `app_open` proxy tool.
+ *
+ * This encapsulates the proxyToolResolver('app_open', ...) pattern so that
+ * callers (app_create auto-open, document-tool, future skill scripts) share
+ * a single implementation with consistent success/failure messaging.
+ */
+
+import type { ProxyResolver, ExecutorResult } from './executors.js';
+
+/**
+ * Open an app on the connected client via the proxy tool resolver.
+ *
+ * @param appId - The ID of the app to open.
+ * @param proxyToolResolver - Optional proxy resolver from the tool context.
+ *   When undefined (e.g. no macOS client connected), returns an informational
+ *   message rather than throwing.
+ * @param extraInput - Optional additional fields to pass alongside app_id
+ *   (e.g. preview metadata).
+ * @returns A stable result string describing the outcome.
+ */
+export async function openAppViaSurface(
+  appId: string,
+  proxyToolResolver: ProxyResolver | undefined,
+  extraInput?: Record<string, unknown>,
+): Promise<string> {
+  if (!proxyToolResolver) {
+    return 'App created but could not be opened (no connected client). Use app_open to open it manually.';
+  }
+
+  try {
+    const result: ExecutorResult = await proxyToolResolver('app_open', {
+      app_id: appId,
+      ...extraInput,
+    });
+    if (result.isError) {
+      return 'Failed to auto-open app. Use app_open to open it manually.';
+    }
+    return result.content;
+  } catch {
+    return 'Failed to auto-open app. Use app_open to open it manually.';
+  }
+}

package/src/tools/apps/registry.ts

@@ -0,0 +1,16 @@
+/**
+ * Registers app proxy tools with the daemon's tool registry.
+ *
+ * Called once at daemon startup via initializeTools(). Only proxy tools
+ * (e.g. app_open) are registered here — non-proxy data tools are now
+ * provided by the app-builder skill via its TOOLS.json manifest.
+ */
+
+import { registerTool } from '../registry.js';
+import { coreAppProxyTools } from './definitions.js';
+
+export function registerAppTools(): void {
+  for (const tool of coreAppProxyTools) {
+    registerTool(tool);
+  }
+}

package/src/tools/assets/materialize.ts

@@ -0,0 +1,218 @@
+/**
+ * asset_materialize — write a stored attachment to a sandbox file path.
+ *
+ * Accepts an attachment ID (from asset_search) and a destination path
+ * within the sandbox working directory. Decodes the base64 content and
+ * writes it to disk so scripts and other tools can consume it as a
+ * regular file.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { eq } from 'drizzle-orm';
+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 { getDb } from '../../memory/db.js';
+import { attachments } from '../../memory/schema.js';
+import { sandboxPolicy } from '../shared/filesystem/path-policy.js';
+import { isAttachmentVisible, type AttachmentContext } from '../../daemon/media-visibility-policy.js';
+import { getConversationThreadType } from '../../memory/conversation-store.js';
+import { getAttachmentSourceConversations } from './search.js';
+
+// ---------------------------------------------------------------------------
+// Size limit — prevent materializing excessively large attachments
+// ---------------------------------------------------------------------------
+
+/** 50 MB ceiling for materialized files. */
+export const MAX_MATERIALIZE_BYTES = 50 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Load an attachment row (including base64 data) by its primary key.
+ *
+ * Not scoped by assistantId because ToolContext doesn't carry it.
+ * Cross-thread isolation is enforced by the visibility check in execute().
+ */
+function loadAttachmentById(
+  attachmentId: string,
+): { id: string; originalFilename: string; mimeType: string; sizeBytes: number; dataBase64: string } | null {
+  const db = getDb();
+  const row = db
+    .select({
+      id: attachments.id,
+      originalFilename: attachments.originalFilename,
+      mimeType: attachments.mimeType,
+      sizeBytes: attachments.sizeBytes,
+      dataBase64: attachments.dataBase64,
+    })
+    .from(attachments)
+    .where(eq(attachments.id, attachmentId))
+    .get();
+
+  return row ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+
+const definition: ToolDefinition = {
+  name: 'asset_materialize',
+  description:
+    'Copy a stored attachment to a file on disk inside the sandbox directory. ' +
+    'Use attachment IDs from asset_search results. The file can then be used ' +
+    'as input to scripts, tools, or other processing.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      attachment_id: {
+        type: 'string',
+        description: 'The ID of the attachment to materialize (from asset_search results).',
+      },
+      destination_path: {
+        type: 'string',
+        description:
+          'Path where the file should be written, relative to (or inside) the sandbox working directory.',
+      },
+    },
+    required: ['attachment_id', 'destination_path'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Tool class
+// ---------------------------------------------------------------------------
+
+class AssetMaterializeTool implements Tool {
+  name = 'asset_materialize';
+  description = definition.description;
+  category = 'assets';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const attachmentId = input.attachment_id as string | undefined;
+    const destinationPath = input.destination_path as string | undefined;
+
+    // --- Input validation ---------------------------------------------------
+
+    if (!attachmentId || typeof attachmentId !== 'string') {
+      return {
+        content: 'Error: attachment_id is required and must be a string.',
+        isError: true,
+      };
+    }
+
+    if (!destinationPath || typeof destinationPath !== 'string') {
+      return {
+        content: 'Error: destination_path is required and must be a string.',
+        isError: true,
+      };
+    }
+
+    // --- Sandbox path enforcement -------------------------------------------
+
+    const pathCheck = sandboxPolicy(destinationPath, context.workingDir, { mustExist: false });
+    if (!pathCheck.ok) {
+      return {
+        content: `Error: ${pathCheck.error}`,
+        isError: true,
+      };
+    }
+
+    const resolvedPath = pathCheck.resolved;
+
+    // --- Load attachment ----------------------------------------------------
+
+    const attachment = loadAttachmentById(attachmentId);
+    if (!attachment) {
+      return {
+        content: `Error: Attachment "${attachmentId}" not found.`,
+        isError: true,
+      };
+    }
+
+    // --- Visibility check ---------------------------------------------------
+    // Reject materialization of attachments from private threads the caller
+    // does not belong to. This prevents cross-thread data leakage.
+
+    const currentThreadType = getConversationThreadType(context.conversationId);
+    const currentContext: AttachmentContext = {
+      conversationId: context.conversationId,
+      isPrivate: currentThreadType === 'private',
+    };
+
+    const sources = getAttachmentSourceConversations(attachmentId);
+    if (sources.length > 0) {
+      const hasStandard = sources.some((s) => s.threadType !== 'private');
+      if (!hasStandard) {
+        // All sources are private — check if the caller is in any of those threads
+        const callerInSourceThread = sources.some(
+          (s) => isAttachmentVisible(
+            { conversationId: s.conversationId, isPrivate: true },
+            currentContext,
+          ),
+        );
+        if (!callerInSourceThread) {
+          return {
+            content:
+              `Error: Attachment "${attachment.originalFilename}" is from a private thread ` +
+              `and cannot be accessed from this context. You can only access this ` +
+              `attachment from within the private thread where it was shared.`,
+            isError: true,
+          };
+        }
+      }
+    }
+
+    // --- Size check ---------------------------------------------------------
+
+    if (attachment.sizeBytes > MAX_MATERIALIZE_BYTES) {
+      return {
+        content:
+          `Error: Attachment "${attachment.originalFilename}" is ${formatBytes(attachment.sizeBytes)}, ` +
+          `which exceeds the ${formatBytes(MAX_MATERIALIZE_BYTES)} materialization limit.`,
+        isError: true,
+      };
+    }
+
+    // --- Decode and write ---------------------------------------------------
+
+    try {
+      const buffer = Buffer.from(attachment.dataBase64, 'base64');
+
+      // Ensure parent directories exist
+      mkdirSync(dirname(resolvedPath), { recursive: true });
+
+      writeFileSync(resolvedPath, buffer);
+
+      return {
+        content:
+          `Materialized "${attachment.originalFilename}" (${attachment.mimeType}, ` +
+          `${formatBytes(attachment.sizeBytes)}) to ${resolvedPath}`,
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error writing file: ${msg}`, isError: true };
+    }
+  }
+}
+
+export const assetMaterializeTool = new AssetMaterializeTool();
+
+registerTool(assetMaterializeTool);