@vertesia/tools-sdk 1.6.0-dev.20261004.085740Z → 1.6.0-dev.20261009.095813Z

package/src/node-loaders.ts

@@ -0,0 +1,131 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseSkillFile } from './SkillCollection.js';
+import type { SkillContentType, SkillDefinition, Tool } from './types.js';
+
+/**
+ * Load all tools from a directory.
+ * Scans for .js files and imports tools that match naming convention.
+ *
+ * Directory structure:
+ * ```
+ * collection/
+ *   tools/
+ *     SearchFundsTool.js    # exports SearchFundsTool
+ *     GetFundDetailsTool.js # exports GetFundDetailsTool
+ * ```
+ *
+ * Naming convention: File should export a Tool with name matching *Tool pattern.
+ *
+ * @param toolsDir - Path to the tools directory (e.g., /path/to/collection/tools)
+ * @returns Promise resolving to array of Tool objects
+ */
+export async function loadToolsFromDirectory(toolsDir: string): Promise<Tool[]> {
+    const tools: Tool[] = [];
+
+    if (!existsSync(toolsDir)) {
+        console.warn(`Tools directory not found: ${toolsDir}`);
+        return tools;
+    }
+
+    let entries: string[];
+    try {
+        entries = readdirSync(toolsDir);
+    } catch {
+        console.warn(`Could not read tools directory: ${toolsDir}`);
+        return tools;
+    }
+
+    for (const entry of entries) {
+        // Only process .js and .ts files that end with Tool
+        if (!entry.endsWith('Tool.js') && !entry.endsWith('Tool.ts')) continue;
+        if (entry.endsWith('.d.ts')) continue;
+
+        const entryPath = join(toolsDir, entry);
+
+        try {
+            const stat = statSync(entryPath);
+            if (!stat.isFile()) continue;
+
+            // Dynamic import - need file:// URL for ESM
+            const fileUrl = pathToFileURL(entryPath).href;
+            const module = await import(fileUrl);
+
+            // Find exported Tool (named export matching filename or any Tool export)
+            const baseName = entry.replace(/\.(js|ts)$/, '');
+            const tool = module[baseName] || module.default;
+
+            if (tool && typeof tool.name === 'string' && typeof tool.run === 'function') {
+                tools.push(tool);
+            } else {
+                console.warn(`No valid Tool export found in ${entry}`);
+            }
+        } catch (err) {
+            console.warn(`Error loading tool from ${entry}:`, err);
+        }
+    }
+
+    return tools;
+}
+
+/**
+ * Load all skills from a directory.
+ * Scans for subdirectories containing SKILL.md files.
+ *
+ * Directory structure:
+ * ```
+ * skills/
+ *   nagare/
+ *     fund-onboarding/
+ *       SKILL.md
+ *     monte-carlo/
+ *       SKILL.md
+ * ```
+ *
+ * @param dirPath - Path to the skills collection directory
+ * @returns Array of parsed skill definitions
+ */
+export function loadSkillsFromDirectory(dirPath: string): SkillDefinition[] {
+    const skills: SkillDefinition[] = [];
+
+    let entries: string[];
+    try {
+        entries = readdirSync(dirPath);
+    } catch {
+        console.warn(`Could not read skills directory: ${dirPath}`);
+        return skills;
+    }
+
+    for (const entry of entries) {
+        const entryPath = join(dirPath, entry);
+
+        try {
+            const stat = statSync(entryPath);
+            if (!stat.isDirectory()) continue;
+
+            // Look for SKILL.md or SKILL.jst
+            const mdPath = join(entryPath, 'SKILL.md');
+            const jstPath = join(entryPath, 'SKILL.jst');
+
+            let content: string | undefined;
+            let contentType: SkillContentType = 'md';
+
+            if (existsSync(mdPath)) {
+                content = readFileSync(mdPath, 'utf-8');
+                contentType = 'md';
+            } else if (existsSync(jstPath)) {
+                content = readFileSync(jstPath, 'utf-8');
+                contentType = 'jst';
+            }
+
+            if (content) {
+                skills.push(parseSkillFile(content, contentType));
+            }
+        } catch (err) {
+            console.warn(`Error loading skill from ${entryPath}:`, err);
+        }
+    }
+
+    return skills;
+}

package/src/sandbox.ts

@@ -0,0 +1,52 @@
+import type { AuthTokenPayload } from '@vertesia/common';
+import { Hono } from 'hono';
+import { AuthSession } from './auth.js';
+import { createSandboxScratch } from './scratch.js';
+import type { ToolServerConfig } from './server/types.js';
+import { createToolServer as createBaseToolServer } from './server.js';
+
+/** Browser-bundle entrypoint. Collections take bundled data; directory loaders are Node-only. */
+export * from './ActivityCollection.js';
+export { AuthSession, authorizeSandbox as authorize } from './auth.js';
+export * from './ContentTypesCollection.js';
+export * from './InteractionCollection.js';
+export * from './RenderingTemplateCollection.js';
+export * from './SkillCollection.js';
+export * from './scratch.js';
+export type { BuildAppPackageOptions } from './server/app-package.js';
+export { buildAppPackage } from './server/app-package.js';
+export * from './server/types.js';
+/** The host supplies non-secret claims; SDK HTTP goes through the sandbox's host-mediated fetch. */
+export function createToolServer(config: ToolServerConfig) {
+    const app = new Hono<{
+        Bindings: { sandboxSession?: AuthTokenPayload };
+        Variables: { toolAuthSession: AuthSession; toolAuthMode: 'sandbox' };
+    }>();
+    app.use('*', async (ctx, next) => {
+        ctx.set('toolAuthMode', 'sandbox');
+        const payload = ctx.env?.sandboxSession;
+        if (payload) {
+            ctx.set(
+                'toolAuthSession',
+                new AuthSession(
+                    'sandbox',
+                    payload,
+                    {
+                        studio: 'https://platform.invalid/studio',
+                        store: 'https://platform.invalid/store',
+                        token: 'https://platform.invalid/token',
+                    },
+                    undefined,
+                    createSandboxScratch(),
+                ),
+            );
+        }
+        await next();
+    });
+    app.route('/', createBaseToolServer(config));
+    return app;
+}
+export * from './site/templates.js';
+export * from './ToolCollection.js';
+export * from './ToolRegistry.js';
+export * from './types.js';

package/src/scratch.ts

@@ -0,0 +1,183 @@
+/**
+ * Per-invocation scratch storage with one API in every host. Under the Vertesia workerd sandbox it is served
+ * by the runtime; on Node (localhost, Vercel) it lives in memory for the request. Either way it is private to
+ * one tool request and gone when the request ends: keep durable results in agent artifacts or files.
+ *
+ * Browser-safe: no Node built-ins, so the sandbox bundle can include it.
+ */
+
+export type ScratchData = string | Uint8Array | ArrayBuffer | Blob;
+
+export interface ScratchEntry {
+    key: string;
+    size: number;
+    contentType: string;
+}
+
+export interface ToolScratch {
+    /** Create or replace `key`. Keys are `/`-separated relative paths, e.g. `work/page-1.json`. */
+    put(key: string, data: ScratchData, options?: { contentType?: string }): Promise<void>;
+    putJson(key: string, value: unknown): Promise<void>;
+    /** `undefined` when the key does not exist. */
+    get(key: string): Promise<Uint8Array | undefined>;
+    getText(key: string): Promise<string | undefined>;
+    getJson<T = unknown>(key: string): Promise<T | undefined>;
+    /** `false` when the key did not exist. */
+    delete(key: string): Promise<boolean>;
+    list(): Promise<ScratchEntry[]>;
+}
+
+export type ScratchErrorCode = 'invalid_key' | 'quota_exceeded' | 'unavailable';
+
+export class ScratchError extends Error {
+    constructor(
+        public readonly code: ScratchErrorCode,
+        message: string,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+        this.name = 'ScratchError';
+    }
+}
+
+/** Matches the sandbox runtime's per-invocation default (`APP_RUNTIME_MAX_SCRATCH_BYTES`). */
+export const DEFAULT_SCRATCH_QUOTA_BYTES = 128 * 1024 * 1024;
+
+/** Guest-visible origin of the sandbox runtime's scratch storage. */
+export const SANDBOX_SCRATCH_ORIGIN = 'http://scratch.invalid';
+
+export function validateScratchKey(key: string): void {
+    if (
+        typeof key !== 'string' ||
+        !key ||
+        key.length > 1024 ||
+        /[\\\0]/.test(key) ||
+        key.split('/').some((part) => part === '.' || part === '..' || !part)
+    )
+        throw new ScratchError('invalid_key', `Invalid scratch key: ${JSON.stringify(key)}`);
+}
+
+/** Always a private copy: later caller mutations cannot change stored content in either backend. */
+async function toBytes(data: ScratchData): Promise<Uint8Array<ArrayBuffer>> {
+    if (typeof data === 'string') return new TextEncoder().encode(data);
+    if (data instanceof Uint8Array) return data.slice();
+    if (data instanceof ArrayBuffer) return new Uint8Array(data.slice(0));
+    return new Uint8Array(await data.arrayBuffer());
+}
+
+function contentTypeOf(data: ScratchData, contentType: string | undefined): string {
+    if (contentType) return contentType;
+    if (typeof data === 'string') return 'text/plain;charset=UTF-8';
+    if (typeof Blob !== 'undefined' && data instanceof Blob && data.type) return data.type;
+    return 'application/octet-stream';
+}
+
+/** Shared convenience methods over the three primitives each backend implements. */
+function withHelpers(base: {
+    put(key: string, bytes: Uint8Array<ArrayBuffer>, contentType: string): Promise<void>;
+    get(key: string): Promise<Uint8Array | undefined>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<ScratchEntry[]>;
+}): ToolScratch {
+    const scratch: ToolScratch = {
+        async put(key, data, options) {
+            validateScratchKey(key);
+            await base.put(key, await toBytes(data), contentTypeOf(data, options?.contentType));
+        },
+        putJson: (key, value) => scratch.put(key, JSON.stringify(value), { contentType: 'application/json' }),
+        async get(key) {
+            validateScratchKey(key);
+            return base.get(key);
+        },
+        async getText(key) {
+            const bytes = await scratch.get(key);
+            return bytes === undefined ? undefined : new TextDecoder().decode(bytes);
+        },
+        async getJson<T>(key: string) {
+            const text = await scratch.getText(key);
+            return text === undefined ? undefined : (JSON.parse(text) as T);
+        },
+        async delete(key) {
+            validateScratchKey(key);
+            return base.delete(key);
+        },
+        list: () => base.list(),
+    };
+    return scratch;
+}
+
+/** In-process scratch for Node hosts. One instance per request; it is garbage collected with the request. */
+export function createMemoryScratch(quota = defaultMemoryQuota()): ToolScratch {
+    const entries = new Map<string, { bytes: Uint8Array; contentType: string }>();
+    let used = 0;
+    return withHelpers({
+        async put(key, bytes, contentType) {
+            const previous = entries.get(key)?.bytes.byteLength ?? 0;
+            if (bytes.byteLength > quota - used + previous)
+                throw new ScratchError('quota_exceeded', `Scratch storage quota of ${quota} bytes exceeded`);
+            entries.set(key, { bytes, contentType });
+            used += bytes.byteLength - previous;
+        },
+        async get(key) {
+            return entries.get(key)?.bytes.slice();
+        },
+        async delete(key) {
+            const entry = entries.get(key);
+            if (!entry) return false;
+            entries.delete(key);
+            used -= entry.bytes.byteLength;
+            return true;
+        },
+        async list() {
+            return [...entries].map(([key, { bytes, contentType }]) => ({ key, size: bytes.byteLength, contentType }));
+        },
+    });
+}
+
+function defaultMemoryQuota(): number {
+    const configured = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+        ?.VERTESIA_SCRATCH_MAX_BYTES;
+    const value = configured === undefined ? DEFAULT_SCRATCH_QUOTA_BYTES : Number(configured);
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error('Invalid VERTESIA_SCRATCH_MAX_BYTES');
+    return value;
+}
+
+/** Scratch served by the Vertesia sandbox runtime; the runtime enforces the quota. */
+export function createSandboxScratch(fetchImpl: typeof fetch = (...args) => fetch(...args)): ToolScratch {
+    const url = (key = '') => `${SANDBOX_SCRATCH_ORIGIN}/${key.split('/').map(encodeURIComponent).join('/')}`;
+    const failure = async (response: Response, operation: string) => {
+        const detail = (await response.text().catch(() => '')).slice(0, 200);
+        if (response.status === 507)
+            return new ScratchError('quota_exceeded', detail || 'Scratch storage quota exceeded');
+        if (response.status === 400) return new ScratchError('invalid_key', detail || 'Invalid scratch key');
+        return new ScratchError('unavailable', `Scratch ${operation} failed with status ${response.status}: ${detail}`);
+    };
+    return withHelpers({
+        async put(key, bytes, contentType) {
+            const response = await fetchImpl(url(key), {
+                method: 'PUT',
+                headers: { 'content-type': contentType },
+                body: bytes,
+            });
+            if (!response.ok) throw await failure(response, 'write');
+        },
+        async get(key) {
+            const response = await fetchImpl(url(key));
+            if (response.status === 404) return undefined;
+            if (!response.ok) throw await failure(response, 'read');
+            return new Uint8Array(await response.arrayBuffer());
+        },
+        async delete(key) {
+            const response = await fetchImpl(url(key), { method: 'DELETE' });
+            if (response.status === 404) return false;
+            if (!response.ok) throw await failure(response, 'delete');
+            return true;
+        },
+        async list() {
+            const response = await fetchImpl(url());
+            if (!response.ok) throw await failure(response, 'list');
+            const body = (await response.json()) as { entries: { key: string; size: number; type: string }[] };
+            return body.entries.map(({ key, size, type }) => ({ key, size, contentType: type }));
+        },
+    });
+}

package/src/server/hooks.ts

@@ -53,6 +53,7 @@ export function createHooksRoute(app: Hono, basePath: string, config: ToolServer
             token: session.token,
             payload: session.payload,
             getClient: () => session.getClient(),
+            scratch: session.scratch,
             metadata,
         };
         const result = await hook.handler(context);
@@ -68,6 +69,7 @@ async function executeEventHook(c: Context, requestContext: ToolContext, hook: A
         token: session.token,
         payload: session.payload,
         getClient: () => session.getClient(),
+        scratch: session.scratch,
     };
     const result = await hook.handler(eventPayload, context);
 

package/src/types.ts

@@ -14,6 +14,7 @@ import type {
     ToolResultContent,
     ToolResultMeta,
 } from '@vertesia/common';
+import type { ToolScratch } from './scratch.js';
 
 export type { ToolExecutionMetadata };
 export type AppEventSubscriptionDefinition = CommonAppEventSubscriptionDefinition;
@@ -58,6 +59,11 @@ export interface ToolExecutionContext {
      * @returns a vertesia client instance
      */
     getClient: () => Promise<VertesiaClient>;
+    /**
+     * Temporary storage private to this request, with the same behavior in the Vertesia sandbox and on
+     * Node hosts (localhost, Vercel). Discarded when the request ends.
+     */
+    scratch: ToolScratch;
 }
 
 export type AppLifecycleHookName = 'install' | 'uninstall';