@swarmclawai/swarmclaw 1.9.2 → 1.9.3

package/README.md

@@ -185,7 +185,7 @@ Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
 - **Wallets**: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
 - **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, SwarmDock, SwarmFeed, and more.
 - **MCP Servers**: connect any Model Context Protocol server (stdio, SSE, or streamable HTTP) and inject its tools into agents alongside built-ins. Configure, test, and assign per-agent from the MCP Servers panel.
-- **Extensions**: external tool extensions, UI modules, hooks, and install/update flows.
+- **Extensions**: external tool extensions, UI modules, hooks, install/update flows, and managed resource manifests for extension-owned agents, routines, local folders, gateways, and setup checks.
 
 ## What SwarmClaw Focuses On
 
@@ -399,6 +399,16 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.3 Highlights
+
+Bundled extension-orchestration release: Paperclip-style managed plugin resources, Hermes-style gateway/setup declarations, and safer local folder access in one release cycle.
+
+- **Managed extension resources.** Extensions can now declare provisionable agents, schedules/routines, local folders, gateway platforms, and setup checks through `managedResources` or Paperclip-compatible top-level aliases.
+- **Deterministic reconciliation.** `/api/extensions/managed-resources` can preview and reconcile extension-owned agents and routines with stable IDs and `managedByExtension` markers.
+- **Trusted local folders.** Extension-declared local folders support root-bounded inspection and recursive listing with traversal and symlink-escape protection.
+- **Operator UI.** The Extensions screen now shows managed-resource badges and a Managed tab with totals plus per-extension reconcile controls.
+- **Extension authoring spec.** `extension_creator` now documents managed resources, gateway declarations, setup checks, and Paperclip-compatible manifest aliases.
+
 ### v1.9.2 Highlights
 
 Bundled competitor-parity release: Hermes-style reasoning hygiene, deterministic delegation routing, Mission Control task workflow polish, OpenClaw export hardening, and Paperclip-style timeout hygiene.

package/electron-dist/main.js

@@ -0,0 +1,218 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const electron_1 = require("electron");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+const server_lifecycle_1 = require("./server-lifecycle");
+const menu_1 = require("./menu");
+const DEV_URL_DEFAULT = 'http://127.0.0.1:3456';
+const LOG_TAIL_BYTES = 1500;
+let mainWindow = null;
+let serverHandle = null;
+let serverLogFile = null;
+let isQuitting = false;
+const gotLock = electron_1.app.requestSingleInstanceLock();
+if (!gotLock) {
+    electron_1.app.quit();
+}
+else {
+    electron_1.app.on('second-instance', () => {
+        if (mainWindow) {
+            if (mainWindow.isMinimized())
+                mainWindow.restore();
+            mainWindow.focus();
+        }
+    });
+    electron_1.app.on('ready', () => void onReady());
+    electron_1.app.on('window-all-closed', () => {
+        if (process.platform !== 'darwin')
+            electron_1.app.quit();
+    });
+    electron_1.app.on('activate', () => {
+        if (mainWindow !== null)
+            return;
+        if (serverHandle) {
+            createMainWindow(serverHandle.url);
+        }
+        else if (!electron_1.app.isPackaged) {
+            createMainWindow(process.env.SWARMCLAW_DEV_URL || DEV_URL_DEFAULT);
+        }
+    });
+    electron_1.app.on('before-quit', () => {
+        isQuitting = true;
+    });
+    electron_1.app.on('will-quit', async (event) => {
+        if (!serverHandle)
+            return;
+        event.preventDefault();
+        try {
+            await serverHandle.stop();
+        }
+        finally {
+            serverHandle = null;
+            electron_1.app.exit(0);
+        }
+    });
+}
+async function onReady() {
+    const paths = (0, paths_1.resolveRuntimePaths)();
+    (0, menu_1.buildAppMenu)(paths, () => mainWindow);
+    const iconPath = resolveIconPath();
+    if (process.platform === 'darwin' && iconPath && electron_1.app.dock) {
+        const img = electron_1.nativeImage.createFromPath(iconPath);
+        if (!img.isEmpty())
+            electron_1.app.dock.setIcon(img);
+    }
+    if (!electron_1.app.isPackaged) {
+        const devUrl = process.env.SWARMCLAW_DEV_URL || DEV_URL_DEFAULT;
+        console.log(`[swarmclaw] dev mode, loading ${devUrl}`);
+        createMainWindow(devUrl);
+        return;
+    }
+    serverLogFile = node_path_1.default.join(electron_1.app.getPath('userData'), 'logs', 'server.log');
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(serverLogFile), { recursive: true });
+    try {
+        serverHandle = await (0, server_lifecycle_1.startEmbeddedServer)({
+            paths,
+            logFile: serverLogFile,
+            onStdout: (c) => process.stdout.write(`[swarmclaw] ${c}`),
+            onStderr: (c) => process.stderr.write(`[swarmclaw] ${c}`),
+            onExit: (code, signal) => {
+                if (!isQuitting) {
+                    console.error(`[swarmclaw] server exited unexpectedly (code=${code}, signal=${signal ?? 'none'})`);
+                    void showServerCrashDialog(code, signal);
+                }
+            },
+        });
+    }
+    catch (err) {
+        await showStartupFailureDialog(err, paths);
+        electron_1.app.exit(1);
+        return;
+    }
+    createMainWindow(serverHandle.url);
+    void Promise.resolve().then(() => __importStar(require('./updater'))).then((m) => m.initAutoUpdater());
+}
+function resolveIconPath() {
+    const candidate = electron_1.app.isPackaged
+        ? node_path_1.default.join(process.resourcesPath, 'icon.png')
+        : node_path_1.default.join(__dirname, '..', 'resources', 'icon.png');
+    return node_fs_1.default.existsSync(candidate) ? candidate : undefined;
+}
+function createMainWindow(startUrl) {
+    const iconPath = resolveIconPath();
+    mainWindow = new electron_1.BrowserWindow({
+        width: 1440,
+        height: 900,
+        minWidth: 1024,
+        minHeight: 640,
+        backgroundColor: '#0b0b0f',
+        show: true,
+        ...(iconPath ? { icon: iconPath } : {}),
+        webPreferences: {
+            contextIsolation: true,
+            nodeIntegration: false,
+            sandbox: false,
+        },
+    });
+    const wc = mainWindow.webContents;
+    if (!electron_1.app.isPackaged)
+        wc.openDevTools({ mode: 'detach' });
+    wc.on('did-start-loading', () => console.log('[swarmclaw] did-start-loading'));
+    wc.on('did-finish-load', () => console.log('[swarmclaw] did-finish-load'));
+    wc.on('did-fail-load', (_e, code, desc, url) => console.error(`[swarmclaw] did-fail-load code=${code} desc=${desc} url=${url}`));
+    wc.on('render-process-gone', (_e, details) => console.error(`[swarmclaw] render-process-gone reason=${details.reason}`));
+    wc.on('unresponsive', () => console.error('[swarmclaw] webContents unresponsive'));
+    mainWindow.on('closed', () => {
+        mainWindow = null;
+    });
+    mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+        if (url.startsWith(startUrl))
+            return { action: 'allow' };
+        void electron_1.shell.openExternal(url);
+        return { action: 'deny' };
+    });
+    void mainWindow.loadURL(startUrl).catch((err) => {
+        console.error('[swarmclaw] loadURL rejected:', err);
+    });
+}
+async function showServerCrashDialog(code, signal) {
+    const buttons = serverLogFile ? ['Open Logs Folder', 'Quit'] : ['Quit'];
+    const quitButtonId = buttons.length - 1;
+    const detail = buildLogDetail(`code=${code ?? 'null'} signal=${signal ?? 'none'}`);
+    const res = await electron_1.dialog.showMessageBox({
+        type: 'error',
+        buttons,
+        defaultId: quitButtonId,
+        cancelId: quitButtonId,
+        title: 'SwarmClaw stopped',
+        message: 'The SwarmClaw server exited unexpectedly.',
+        detail,
+    });
+    if (serverLogFile && res.response === 0)
+        electron_1.shell.showItemInFolder(serverLogFile);
+    electron_1.app.exit(1);
+}
+async function showStartupFailureDialog(err, paths) {
+    const message = err instanceof Error ? err.message : String(err);
+    const base = `${message}\n\nStandalone entry: ${paths.standaloneEntry}\nData dir: ${paths.dataDir}`;
+    const detail = buildLogDetail(base);
+    const buttons = serverLogFile ? ['Open Logs Folder', 'Quit'] : ['Quit'];
+    const quitButtonId = buttons.length - 1;
+    const res = await electron_1.dialog.showMessageBox({
+        type: 'error',
+        buttons,
+        defaultId: quitButtonId,
+        cancelId: quitButtonId,
+        title: 'SwarmClaw failed to start',
+        message: 'The embedded server did not start.',
+        detail,
+    });
+    if (serverLogFile && res.response === 0)
+        electron_1.shell.showItemInFolder(serverLogFile);
+}
+function buildLogDetail(base) {
+    if (!serverLogFile)
+        return base;
+    const tail = (0, server_lifecycle_1.tailLogFile)(serverLogFile, LOG_TAIL_BYTES).trim();
+    if (!tail)
+        return `${base}\n\nLog file: ${serverLogFile}\n(no output captured yet)`;
+    return `${base}\n\nLog tail (${serverLogFile}):\n${tail}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

package/src/app/api/extensions/managed-resources/route.test.ts

@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict'
+import test, { afterEach } from 'node:test'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+import { getExtensionManager } from '@/lib/server/extensions'
+import { loadAgents, loadSchedules, loadSettings, saveAgents, saveSchedules, saveSettings } from '@/lib/server/storage'
+import { GET, POST } from './route'
+
+const originalAgents = loadAgents()
+const originalSchedules = loadSchedules()
+const originalSettings = loadSettings()
+
+let seq = 0
+
+function extensionId(prefix: string): string {
+  seq += 1
+  return `${prefix}_${Date.now()}_${seq}`
+}
+
+afterEach(() => {
+  saveAgents(originalAgents)
+  saveSchedules(originalSchedules)
+  saveSettings(originalSettings)
+})
+
+test('managed resources route reconciles one extension', async () => {
+  const id = extensionId('route_managed_resources')
+  getExtensionManager().registerBuiltin(id, {
+    name: 'Route Managed Fixture',
+    managedResources: {
+      agents: [
+        {
+          agentKey: 'operator',
+          displayName: 'Route Operator',
+          provider: 'openai',
+          model: 'gpt-4o-mini',
+        },
+      ],
+    },
+  })
+
+  const before = await GET(new Request('http://local/api/extensions/managed-resources'))
+  assert.equal(before.status, 200)
+  const beforeBody = await before.json()
+  const extension = beforeBody.extensions.find((entry: { extensionId: string }) => entry.extensionId === id)
+  assert.equal(extension.agents[0].status, 'missing')
+
+  const response = await POST(new Request('http://local/api/extensions/managed-resources', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ action: 'reconcile', extensionId: id }),
+  }))
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.createdAgents.length, 1)
+  const agent = loadAgents()[body.createdAgents[0]]
+  assert.ok(agent)
+  assert.equal(agent.managedByExtension?.extensionId, id)
+})
+
+test('managed resources route configures and lists a local folder', async () => {
+  const id = extensionId('route_managed_folder')
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-route-folder-'))
+  fs.mkdirSync(path.join(tempDir, 'inputs'))
+  fs.writeFileSync(path.join(tempDir, 'inputs', 'task.txt'), 'task\n')
+
+  getExtensionManager().registerBuiltin(id, {
+    name: 'Route Folder Fixture',
+    managedResources: {
+      localFolders: [
+        {
+          folderKey: 'workspace',
+          displayName: 'Workspace Folder',
+          access: 'readWrite',
+          requiredDirectories: ['inputs'],
+          requiredFiles: ['inputs/task.txt'],
+        },
+      ],
+    },
+  })
+
+  const configure = await POST(new Request('http://local/api/extensions/managed-resources', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      action: 'configure_local_folder',
+      extensionId: id,
+      folderKey: 'workspace',
+      path: tempDir,
+    }),
+  }))
+  assert.equal(configure.status, 200)
+  const configured = await configure.json()
+  assert.equal(configured.status.healthy, true)
+
+  const listing = await GET(new Request(`http://local/api/extensions/managed-resources?action=list_local_folder&extensionId=${encodeURIComponent(id)}&folderKey=workspace&recursive=true`))
+  assert.equal(listing.status, 200)
+  const listingBody = await listing.json()
+  assert.ok(listingBody.entries.some((entry: { path: string }) => entry.path === 'inputs/task.txt'))
+
+  const traversal = await POST(new Request('http://local/api/extensions/managed-resources', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      action: 'list_local_folder',
+      extensionId: id,
+      folderKey: 'workspace',
+      relativePath: '../outside',
+    }),
+  }))
+  assert.equal(traversal.status, 400)
+
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})

package/src/app/api/extensions/managed-resources/route.ts

@@ -0,0 +1,116 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import {
+  inspectExtensionLocalFolder,
+  listExtensionLocalFolderEntries,
+  listExtensionManagedResources,
+  reconcileExtensionManagedResources,
+  setExtensionLocalFolderConfig,
+} from '@/lib/server/extension-managed-resources'
+import { errorMessage } from '@/lib/shared-utils'
+import '@/lib/server/builtin-extensions'
+
+export const dynamic = 'force-dynamic'
+
+function badRequest(message: string) {
+  return NextResponse.json({ error: message }, { status: 400 })
+}
+
+function optionalText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const action = searchParams.get('action')
+
+  try {
+    if (action === 'inspect_local_folder') {
+      const extensionId = optionalText(searchParams.get('extensionId'))
+      const folderKey = optionalText(searchParams.get('folderKey'))
+      if (!extensionId || !folderKey) return badRequest('extensionId and folderKey required')
+      return NextResponse.json(await inspectExtensionLocalFolder({
+        extensionId,
+        folderKey,
+      }))
+    }
+
+    if (action === 'list_local_folder') {
+      const extensionId = optionalText(searchParams.get('extensionId'))
+      const folderKey = optionalText(searchParams.get('folderKey'))
+      if (!extensionId || !folderKey) return badRequest('extensionId and folderKey required')
+      return NextResponse.json(await listExtensionLocalFolderEntries({
+        extensionId,
+        folderKey,
+        relativePath: optionalText(searchParams.get('relativePath')),
+        recursive: searchParams.get('recursive') === 'true',
+        maxEntries: Number(searchParams.get('maxEntries') || 1000),
+      }))
+    }
+
+    return NextResponse.json(listExtensionManagedResources())
+  } catch (err: unknown) {
+    return badRequest(errorMessage(err))
+  }
+}
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const input = body && typeof body === 'object' ? body as Record<string, unknown> : {}
+  const action = optionalText(input.action)
+
+  try {
+    if (action === 'reconcile') {
+      return NextResponse.json(reconcileExtensionManagedResources(optionalText(input.extensionId)))
+    }
+
+    if (action === 'configure_local_folder') {
+      const extensionId = optionalText(input.extensionId)
+      const folderKey = optionalText(input.folderKey)
+      const folderPath = optionalText(input.path)
+      if (!extensionId || !folderKey || !folderPath) {
+        return badRequest('extensionId, folderKey, and path required')
+      }
+      const access = input.access === 'read' || input.access === 'readWrite'
+        ? input.access
+        : undefined
+      const config = setExtensionLocalFolderConfig({
+        extensionId,
+        folderKey,
+        path: folderPath,
+        access,
+      })
+      const status = await inspectExtensionLocalFolder({ extensionId, folderKey })
+      return NextResponse.json({ ok: true, config, status })
+    }
+
+    if (action === 'inspect_local_folder') {
+      const extensionId = optionalText(input.extensionId)
+      const folderKey = optionalText(input.folderKey)
+      if (!extensionId || !folderKey) return badRequest('extensionId and folderKey required')
+      return NextResponse.json(await inspectExtensionLocalFolder({
+        extensionId,
+        folderKey,
+        overridePath: optionalText(input.path),
+      }))
+    }
+
+    if (action === 'list_local_folder') {
+      const extensionId = optionalText(input.extensionId)
+      const folderKey = optionalText(input.folderKey)
+      if (!extensionId || !folderKey) return badRequest('extensionId and folderKey required')
+      return NextResponse.json(await listExtensionLocalFolderEntries({
+        extensionId,
+        folderKey,
+        relativePath: optionalText(input.relativePath),
+        recursive: input.recursive === true,
+        maxEntries: typeof input.maxEntries === 'number' ? input.maxEntries : undefined,
+      }))
+    }
+
+    return badRequest('action required')
+  } catch (err: unknown) {
+    return badRequest(errorMessage(err))
+  }
+}

package/src/cli/index.js

@@ -526,6 +526,8 @@ const COMMAND_GROUPS = [
       cmd('settings-set', 'PUT', '/extensions/settings', 'Set extension settings (use --query extensionId=extension_name and --data JSON)', { expectsJsonBody: true }),
       cmd('ui', 'GET', '/extensions/ui', 'List extension UI modules (use --query type=sidebar|header|chat_actions|connectors)'),
       cmd('builtins', 'GET', '/extensions/builtins', 'List built-in extensions'),
+      cmd('managed-resources', 'GET', '/extensions/managed-resources', 'Preview extension-managed agents, routines, folders, gateways, and setup checks'),
+      cmd('managed-resources-action', 'POST', '/extensions/managed-resources', 'Reconcile or inspect extension-managed resources', { expectsJsonBody: true }),
     ],
   },
   {

package/src/cli/spec.js

@@ -386,6 +386,8 @@ const COMMAND_GROUPS = {
       install: { description: 'Install extension by URL', method: 'POST', path: '/extensions/install' },
       'settings-get': { description: 'Read extension settings (supports --query extensionId=...)', method: 'GET', path: '/extensions/settings' },
       'settings-set': { description: 'Write extension settings (supports --query extensionId=... and --data JSON)', method: 'PUT', path: '/extensions/settings' },
+      'managed-resources': { description: 'Preview extension-managed agents, routines, folders, gateways, and setup checks', method: 'GET', path: '/extensions/managed-resources' },
+      'managed-resources-action': { description: 'Reconcile or inspect extension-managed resources', method: 'POST', path: '/extensions/managed-resources' },
     },
   },
   providers: {