feat(owletto-backend): multi-org execute + search MCP tools

.github/workflows/ci.yml

@@ -28,10 +28,16 @@ jobs:
       - name: Build core package first
         run: cd packages/core && bun run build
 
+      - name: Build owletto SDK for backend tests
+        run: cd packages/owletto-sdk && bun run build
+
       - name: Run tests with coverage
         run: |
           # Run core, gateway, and cli tests fully
           bun test packages/core packages/gateway packages/cli --coverage
+          # Owletto backend sandbox/auth coverage for MCP execute/search changes
+          bun test packages/owletto-backend/src/__tests__/unit/sandbox
+          bun test packages/owletto-backend/src/auth/__tests__/tool-access.test.ts
           # Worker tests that don't transitively load pi-coding-agent runtime (WASM unavailable on CI)
           bun test packages/worker/src/__tests__/embedded-tools.test.ts packages/worker/src/__tests__/model-resolver.test.ts packages/worker/src/__tests__/tool-policy.test.ts packages/worker/src/__tests__/processor.test.ts packages/worker/src/__tests__/audio-provider-suggestions.test.ts packages/worker/src/__tests__/generated-media.test.ts packages/worker/src/__tests__/tool-implementations.test.ts packages/worker/src/__tests__/instructions.test.ts packages/worker/src/__tests__/custom-tools.test.ts
 

.gitignore

@@ -31,6 +31,8 @@ packages/**/*.d.ts.map
 !packages/cli/bin/*.js
 # Tailwind config is a JS config file, not a build artifact
 !packages/gateway/tailwind.config.js
+# Hand-authored type shims for optional native modules (not build output)
+!packages/**/src/types/*.d.ts
 tsconfig.tsbuildinfo
 **/tsconfig.tsbuildinfo
 

docker/app/Dockerfile

@@ -8,8 +8,10 @@ FROM node:22-slim AS builder
 WORKDIR /app
 
 # Bun for workspace install + tsc. git needed because some deps ship git URLs.
+# python3 + build-essential needed for isolated-vm native build (node-gyp).
 RUN apt-get update && apt-get install -y --no-install-recommends \
       git ca-certificates curl unzip \
+      python3 build-essential \
     && rm -rf /var/lib/apt/lists/* \
     && curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash \
     && chmod +x /usr/local/bin/bun

packages/landing/src/content/docs/reference/owletto-cli.md

@@ -138,11 +138,14 @@ npx owletto@latest run
 # Search knowledge
 npx owletto@latest run search_knowledge '{"query":"Acme"}'
 
-# Read saved content
-npx owletto@latest run read_knowledge '{"query":"customer preferences"}'
-
 # Save new knowledge
 npx owletto@latest run save_knowledge '{"content":"Prefers weekly summaries","semantic_type":"preference","metadata":{}}'
+
+# Discover SDK methods (namespaces, signatures, examples)
+npx owletto@latest run search '{"query":"watchers.create"}'
+
+# Run a TypeScript script over the typed client SDK
+npx owletto@latest run execute '{"script":"export default async (ctx, client) => client.entities.list({ entity_type: \"company\", limit: 5 })"}'
 ```
 
 This is the most direct way to inspect or test Owletto behavior outside an agent runtime.
@@ -151,13 +154,13 @@ This is the most direct way to inspect or test Owletto behavior outside an agent
 
 The exact tool list depends on the endpoint and your session scope. Run `owletto run` with no arguments to see what is available.
 
-**Core memory:** `search_knowledge`, `read_knowledge`, `save_knowledge`
+**Core memory:** `search_knowledge`, `save_knowledge`
 
-**Watchers:** `list_watchers`, `get_watcher`
+**SDK surface:** `search` (method discovery), `execute` (run TS over the typed `ClientSDK` — replaces the previous `manage_*` MCP tools; reach handlers via `client.<namespace>.<method>(...)` from inside the script)
 
-**Organization:** `list_organizations`, `switch_organization` (unscoped endpoint only)
+**Read-only SQL:** `query_sql` (admin/owner only)
 
-**Admin / workspace** (admin sessions only): `manage_entity`, `manage_entity_schema`, `manage_connections`, `manage_feeds`, `manage_auth_profiles`, `manage_operations`, `manage_watchers`, `manage_classifiers`, `query_sql`
+**Organization:** `list_organizations`, `switch_organization` (exposed on both unscoped and scoped endpoints)
 
 ## Other Useful Commands
 

packages/owletto-backend/package.json

@@ -18,15 +18,13 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.13.7",
-    "@jitl/quickjs-ng-wasmfile-release-asyncify": "0.31.0",
     "@lobu/core": "workspace:*",
     "@lobu/gateway": "workspace:*",
     "@lobu/owletto-sdk": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@polyglot-sql/sdk": "^0.1.13",
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^2.0.7",
-    "@sebastianwessel/quickjs": "^3.0.1",
     "@sentry/node": "^9.0.0",
     "@sinclair/typebox": "^0.34.41",
     "@slack/socket-mode": "^2.0.6",
@@ -58,5 +56,8 @@
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
     "vitest": "^2.1.8"
+  },
+  "optionalDependencies": {
+    "isolated-vm": "^5.0.4"
   }
 }

packages/owletto-backend/src/__tests__/integration/mcp/auth.test.ts

@@ -262,17 +262,15 @@ describe('MCP Authentication', () => {
       const body = await response.json();
       const toolNames = body.result.tools.map((tool: any) => tool.name);
 
+      // Public reads survive: search_knowledge, search (SDK discovery).
       expect(toolNames).toContain('search_knowledge');
+      expect(toolNames).toContain('search');
+      // Writes and admin reads must not be visible to anonymous public callers.
       expect(toolNames).not.toContain('save_knowledge');
       expect(toolNames).not.toContain('query_sql');
-
-      const manageEntity = body.result.tools.find((tool: any) => tool.name === 'manage_entity');
-      expect(manageEntity).toBeDefined();
-      expect(manageEntity.inputSchema.properties.action.enum).toEqual([
-        'list',
-        'get',
-        'list_links',
-      ]);
+      expect(toolNames).not.toContain('execute');
+      // Legacy `manage_*` tools are no longer registered as external MCP tools.
+      expect(toolNames).not.toContain('manage_entity');
     });
 
     it('allows anonymous public-read tool calls on public org MCP routes', async () => {
@@ -379,16 +377,11 @@ describe('MCP Authentication', () => {
       const toolNames = body.result.tools.map((tool: any) => tool.name);
 
       expect(toolNames).toContain('search_knowledge');
+      expect(toolNames).toContain('search');
       expect(toolNames).not.toContain('save_knowledge');
       expect(toolNames).not.toContain('query_sql');
-
-      const manageEntity = body.result.tools.find((tool: any) => tool.name === 'manage_entity');
-      expect(manageEntity).toBeDefined();
-      expect(manageEntity.inputSchema.properties.action.enum).toEqual([
-        'list',
-        'get',
-        'list_links',
-      ]);
+      expect(toolNames).not.toContain('execute');
+      expect(toolNames).not.toContain('manage_entity');
     });
 
     it('should reject expired OAuth access token', async () => {
@@ -730,7 +723,10 @@ describe('MCP Authentication', () => {
       expect(body.error?.message).toContain("Agent 'missing-agent' was not found");
     });
 
-    it('hides org switching tools on scoped /mcp/:org routes', async () => {
+    it('exposes org switching tools on scoped /mcp/:org routes too', async () => {
+      // PR-2: list_organizations + switch_organization are no longer
+      // gated behind the unscoped /mcp endpoint. Scoped sessions can still
+      // call switch_organization to move off the URL pin.
       const { token } = await createTestAccessToken(user.id, org.id, client.client_id);
 
       const response = await post(`/mcp/${org.slug}`, {
@@ -747,8 +743,8 @@ describe('MCP Authentication', () => {
       const body = await response.json();
       const toolNames = body.result.tools.map((tool: any) => tool.name);
 
-      expect(toolNames).not.toContain('list_organizations');
-      expect(toolNames).not.toContain('switch_organization');
+      expect(toolNames).toContain('list_organizations');
+      expect(toolNames).toContain('switch_organization');
     });
   });
 
@@ -924,12 +920,19 @@ describe('MCP Authentication', () => {
 
       expect(result.tools).toBeInstanceOf(Array);
 
-      // Verify expected tools are present
+      // Verify expected tools are present. The legacy `manage_*`,
+      // `read_knowledge`, `get_watcher`, `list_watchers` MCP tools are now
+      // internal-only and reachable via the SDK from `execute` scripts.
       const toolNames = result.tools.map((t: any) => t.name);
       expect(toolNames).toContain('search_knowledge');
-      expect(toolNames).toContain('read_knowledge');
-      expect(toolNames).toContain('get_watcher');
-      expect(toolNames).toContain('list_watchers');
+      expect(toolNames).toContain('save_knowledge');
+      expect(toolNames).toContain('search');
+      expect(toolNames).toContain('execute');
+      expect(toolNames).not.toContain('read_knowledge');
+      expect(toolNames).not.toContain('get_watcher');
+      expect(toolNames).not.toContain('list_watchers');
+      expect(toolNames).not.toContain('manage_entity');
+      expect(toolNames).not.toContain('join_organization');
     });
 
     it('should include tool descriptions', async () => {