@vertesia/tools-sdk 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261008.064737Z

package/lib/sandbox.js

@@ -0,0 +1,35 @@
+import { Hono } from 'hono';
+import { AuthSession } from './auth.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 { 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) {
+    const app = new Hono();
+    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',
+            }));
+        }
+        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';
+//# sourceMappingURL=sandbox.js.map

package/lib/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEvE,iGAAiG;AACjG,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,gBAAgB,IAAI,SAAS,EAAE,MAAM,WAAW,CAAC;AACvE,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,cAAc,mBAAmB,CAAC;AAClC,oGAAoG;AACpG,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACrD,MAAM,GAAG,GAAG,IAAI,IAAI,EAGhB,CAAC;IACL,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC7B,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC;QACxC,IAAI,OAAO,EAAE,CAAC;YACV,GAAG,CAAC,GAAG,CACH,iBAAiB,EACjB,IAAI,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE;gBAChC,MAAM,EAAE,iCAAiC;gBACzC,KAAK,EAAE,gCAAgC;gBACvC,KAAK,EAAE,gCAAgC;aAC1C,CAAC,CACL,CAAC;QACN,CAAC;QACD,MAAM,IAAI,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC;AACf,CAAC;AACD,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/package.json

@@ -1,34 +1,39 @@
 {
   "name": "@vertesia/tools-sdk",
-  "version": "1.6.0-dev.20260923.085325Z",
+  "version": "1.6.0-dev.20261008.064737Z",
   "description": "Tools SDK - utilities for building remote tools",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "files": [
     "lib",
-    "src"
+    "src",
+    "!src/**/*.test.*"
   ],
   "license": "Apache-2.0",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./sandbox": {
+      "types": "./lib/sandbox.d.ts",
+      "default": "./lib/sandbox.js"
     }
   },
   "devDependencies": {
-    "@types/node": "^24.13.5",
+    "@types/node": "^24.19.0",
     "@vertesia/tsconfig": "0.1.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.1"
+    "vitest": "5.0.2"
   },
   "peerDependencies": {
-    "hono": "^4.13.8"
+    "hono": "^4.13.13"
   },
   "dependencies": {
-    "@llumiverse/common": "1.6.0-dev.20260923.085100Z",
-    "@vertesia/client": "1.6.0-dev.20260923.085325Z",
-    "@vertesia/common": "1.6.0-dev.20260923.085325Z",
+    "@llumiverse/common": "1.6.0-dev.20261008.064411Z",
+    "@vertesia/client": "1.6.0-dev.20261008.064737Z",
+    "@vertesia/common": "1.6.0-dev.20261008.064737Z",
     "jose": "^6.2.12",
     "zod": "4.6.5"
   },
@@ -46,13 +51,13 @@
     "agents",
     "typescript"
   ],
-  "gitHead": "8732631fd8099bdcab4f5375da2309f3cff34e19",
+  "gitHead": "8ee3a33e9a7c3dbcd13937e971cbdcc5fad56717",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",
-    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "typecheck:test": "tsc --checkers 1 -p tsconfig.test.json --noEmit",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",
-    "build": "pnpm run clean:lib && tsc -p tsconfig.json",
+    "build": "pnpm run clean:lib && tsc --checkers 1 -p tsconfig.json",
     "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
   }
 }

package/src/SkillCollection.ts

@@ -1,5 +1,3 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
 import type { ToolDefinition } from '@llumiverse/common';
 import type { AgentToolDefinition } from '@vertesia/common';
 import type { Context } from 'hono';
@@ -427,64 +425,3 @@ export async function loadSkillFromFile(
     const contentType: SkillContentType = filePath.endsWith('.jst') ? 'jst' : 'md';
     return parseSkillFile(content, contentType);
 }
-
-/**
- * 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/ToolCollection.ts

@@ -1,6 +1,3 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import type { AgentToolDefinition } from '@vertesia/common';
 import type { Context } from 'hono';
 import { HTTPException } from 'hono/http-exception';
@@ -158,68 +155,3 @@ function readPayload(ctx: Context): ToolExecutionPayload {
             'Invalid or missing tool execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }',
     });
 }
-
-/**
- * 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;
-}

package/src/auth.ts

@@ -49,7 +49,22 @@ export interface ToolContext {
     runId?: string;
 }
 
+/** Sandbox authorization never accepts a credential supplied by the guest request. */
+export async function authorizeSandbox(
+    ctx: Context,
+    _endpointOverrides?: EndpointOverrides,
+    _toolContext?: ToolContext,
+) {
+    const session = ctx.get('toolAuthSession') as AuthSession | undefined;
+    if (!session) throw new HTTPException(401, { message: 'Missing sandbox host session' });
+    return session;
+}
+
 export async function authorize(ctx: Context, endpointOverrides?: EndpointOverrides, toolContext?: ToolContext) {
+    if (ctx.get('toolAuthMode') === 'sandbox') return authorizeSandbox(ctx);
+    // A sandbox host can bind a session in application middleware. HTTP headers cannot set this value.
+    const boundSession = ctx.get('toolAuthSession') as AuthSession | undefined;
+    if (boundSession) return boundSession;
     const auth = ctx.req.header('Authorization');
     if (!auth) {
         throw new HTTPException(401, {

package/src/index.ts

@@ -3,6 +3,7 @@ export { AuthSession, authorize } from './auth.js';
 export * from './ContentTypesCollection.js';
 export { copyRuntimeAssets } from './copy-assets.js';
 export * from './InteractionCollection.js';
+export { loadSkillsFromDirectory, loadToolsFromDirectory } from './node-loaders.js';
 export * from './RenderingTemplateCollection.js';
 export * from './SkillCollection.js';
 export type { BuildAppPackageOptions } from './server/app-package.js';

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,44 @@
+import type { AuthTokenPayload } from '@vertesia/common';
+import { Hono } from 'hono';
+import { AuthSession } from './auth.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 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',
+                }),
+            );
+        }
+        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/ActivityCollection.test.ts

@@ -1,162 +0,0 @@
-import type { RemoteActivityExecutionPayload } from '@vertesia/common';
-import type { Context } from 'hono';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { ActivityCollection, type ActivityDefinition } from './ActivityCollection.js';
-
-type MockContext = Context & {
-    json: ReturnType<typeof vi.fn>;
-    req: { header: ReturnType<typeof vi.fn>; url: string };
-    set: ReturnType<typeof vi.fn>;
-};
-
-vi.mock('./auth.js', () => ({
-    authorize: vi.fn().mockResolvedValue({ token: 'test-token' }),
-}));
-
-const mockActivity: ActivityDefinition = {
-    name: 'analyze_sentiment',
-    title: 'Analyze Sentiment',
-    description: 'Analyzes text sentiment',
-    input_schema: {
-        type: 'object',
-        properties: { text: { type: 'string' } },
-        required: ['text'],
-    },
-    output_schema: {
-        type: 'object',
-        properties: { score: { type: 'number' } },
-    },
-    run: vi.fn().mockResolvedValue({ score: 0.95 }),
-};
-
-const mockFailingActivity: ActivityDefinition = {
-    name: 'fail_always',
-    description: 'Always fails',
-    run: vi.fn().mockRejectedValue(new Error('Intentional failure')),
-};
-
-function createCollection(activities: ActivityDefinition[] = [mockActivity]) {
-    return new ActivityCollection({
-        name: 'test-collection',
-        title: 'Test Collection',
-        description: 'A test collection',
-        activities,
-    });
-}
-
-beforeEach(() => {
-    vi.clearAllMocks();
-});
-
-describe('ActivityCollection', () => {
-    describe('getActivityDefinitions', () => {
-        it('returns correct metadata for all registered activities', () => {
-            const coll = createCollection([mockActivity, mockFailingActivity]);
-            const defs = coll.getActivityDefinitions();
-
-            expect(defs).toHaveLength(2);
-            expect(defs[0]).toEqual({
-                name: 'analyze_sentiment',
-                title: 'Analyze Sentiment',
-                description: 'Analyzes text sentiment',
-                input_schema: mockActivity.input_schema,
-                output_schema: mockActivity.output_schema,
-            });
-            expect(defs[1]).toEqual({
-                name: 'fail_always',
-                title: undefined,
-                description: 'Always fails',
-                input_schema: undefined,
-                output_schema: undefined,
-            });
-        });
-
-        it('returns empty array when no activities registered', () => {
-            const coll = createCollection([]);
-            expect(coll.getActivityDefinitions()).toEqual([]);
-        });
-    });
-
-    describe('getActivity', () => {
-        it('returns the activity by name', () => {
-            const coll = createCollection();
-            const activity = coll.getActivity('analyze_sentiment');
-            expect(activity.name).toBe('analyze_sentiment');
-            expect(activity.run).toBeDefined();
-        });
-
-        it('throws 404 for unknown activity name', () => {
-            const coll = createCollection();
-            expect(() => coll.getActivity('nonexistent')).toThrow();
-        });
-    });
-
-    describe('iterator', () => {
-        it('iterates over all activities', () => {
-            const coll = createCollection([mockActivity, mockFailingActivity]);
-            const names = [...coll].map((a) => a.name);
-            expect(names).toEqual(['analyze_sentiment', 'fail_always']);
-        });
-    });
-
-    describe('execute', () => {
-        const createMockContext = (): MockContext => {
-            const jsonFn = vi.fn().mockReturnThis();
-            return {
-                json: jsonFn,
-                req: {
-                    header: vi.fn().mockReturnValue('Bearer test-token'),
-                    url: 'http://localhost/api/activities',
-                },
-                set: vi.fn(),
-            } as unknown as MockContext;
-        };
-
-        const payload: RemoteActivityExecutionPayload = {
-            activity_name: 'analyze_sentiment',
-            params: { text: 'Hello world' },
-            metadata: {
-                app_install_id: 'install-1',
-            },
-        };
-
-        it('calls the correct activity handler and returns result', async () => {
-            const coll = createCollection();
-            const ctx = createMockContext();
-
-            await coll.execute(ctx, payload);
-
-            expect(mockActivity.run).toHaveBeenCalledWith(payload, expect.objectContaining({ token: 'test-token' }));
-            expect(ctx.json).toHaveBeenCalledWith({
-                result: { score: 0.95 },
-                is_error: false,
-            });
-        });
-
-        it('returns is_error with message when activity throws', async () => {
-            const coll = createCollection([mockFailingActivity]);
-            const ctx = createMockContext();
-
-            const failPayload: RemoteActivityExecutionPayload = {
-                ...payload,
-                activity_name: 'fail_always',
-            };
-
-            await coll.execute(ctx, failPayload);
-
-            expect(ctx.json).toHaveBeenCalledWith({ result: null, is_error: true, error: 'Intentional failure' }, 500);
-        });
-
-        it('throws 404 when activity_name is not found', async () => {
-            const coll = createCollection();
-            const ctx = createMockContext();
-
-            const unknownPayload: RemoteActivityExecutionPayload = {
-                ...payload,
-                activity_name: 'nonexistent',
-            };
-
-            await expect(coll.execute(ctx, unknownPayload)).rejects.toThrow();
-        });
-    });
-});