feat: plugin system + voice-call

src/plugins/discovery.ts

@@ -61,10 +61,17 @@ function deriveIdHint(params: {
   hasMultipleExtensions: boolean;
 }): string {
   const base = path.basename(params.filePath, path.extname(params.filePath));
-  const packageName = params.packageName?.trim();
-  if (!packageName) return base;
-  if (!params.hasMultipleExtensions) return packageName;
-  return `${packageName}/${base}`;
+  const rawPackageName = params.packageName?.trim();
+  if (!rawPackageName) return base;
+
+  // Prefer the unscoped name so config keys stay stable even when the npm
+  // package is scoped (example: @clawdbot/voice-call -> voice-call).
+  const unscoped = rawPackageName.includes("/")
+    ? (rawPackageName.split("/").pop() ?? rawPackageName)
+    : rawPackageName;
+
+  if (!params.hasMultipleExtensions) return unscoped;
+  return `${unscoped}/${base}`;
 }
 
 function addCandidate(params: {

src/plugins/install.ts

@@ -0,0 +1,236 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { CONFIG_DIR, resolveUserPath } from "../utils.js";
+
+type PluginInstallLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type PackageManifest = {
+  name?: string;
+  dependencies?: Record<string, string>;
+  clawdbot?: { extensions?: string[] };
+};
+
+export type InstallPluginResult =
+  | {
+      ok: true;
+      pluginId: string;
+      targetDir: string;
+      manifestName?: string;
+      extensions: string[];
+    }
+  | { ok: false; error: string };
+
+const defaultLogger: PluginInstallLogger = {};
+
+function unscopedPackageName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) return trimmed;
+  return trimmed.includes("/")
+    ? (trimmed.split("/").pop() ?? trimmed)
+    : trimmed;
+}
+
+function safeDirName(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return trimmed;
+  return trimmed.replaceAll("/", "__");
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T> {
+  const raw = await fs.readFile(filePath, "utf-8");
+  return JSON.parse(raw) as T;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolvePackedPackageDir(extractDir: string): Promise<string> {
+  const direct = path.join(extractDir, "package");
+  if (await fileExists(direct)) return direct;
+
+  const entries = await fs.readdir(extractDir, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  if (dirs.length !== 1) {
+    throw new Error(`unexpected archive layout (dirs: ${dirs.join(", ")})`);
+  }
+  const onlyDir = dirs[0];
+  if (!onlyDir) {
+    throw new Error("unexpected archive layout (no package dir found)");
+  }
+  return path.join(extractDir, onlyDir);
+}
+
+async function ensureClawdbotExtensions(manifest: PackageManifest) {
+  const extensions = manifest.clawdbot?.extensions;
+  if (!Array.isArray(extensions)) {
+    throw new Error("package.json missing clawdbot.extensions");
+  }
+  const list = extensions
+    .map((e) => (typeof e === "string" ? e.trim() : ""))
+    .filter(Boolean);
+  if (list.length === 0) {
+    throw new Error("package.json clawdbot.extensions is empty");
+  }
+  return list;
+}
+
+export async function installPluginFromArchive(params: {
+  archivePath: string;
+  extensionsDir?: string;
+  timeoutMs?: number;
+  logger?: PluginInstallLogger;
+}): Promise<InstallPluginResult> {
+  const logger = params.logger ?? defaultLogger;
+  const timeoutMs = params.timeoutMs ?? 120_000;
+
+  const archivePath = resolveUserPath(params.archivePath);
+  if (!(await fileExists(archivePath))) {
+    return { ok: false, error: `archive not found: ${archivePath}` };
+  }
+
+  const extensionsDir = params.extensionsDir
+    ? resolveUserPath(params.extensionsDir)
+    : path.join(CONFIG_DIR, "extensions");
+  await fs.mkdir(extensionsDir, { recursive: true });
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-plugin-"));
+  const extractDir = path.join(tmpDir, "extract");
+  await fs.mkdir(extractDir, { recursive: true });
+
+  logger.info?.(`Extracting ${archivePath}…`);
+  const tarRes = await runCommandWithTimeout(
+    ["tar", "-xzf", archivePath, "-C", extractDir],
+    { timeoutMs },
+  );
+  if (tarRes.code !== 0) {
+    return {
+      ok: false,
+      error: `failed to extract archive: ${tarRes.stderr.trim() || tarRes.stdout.trim()}`,
+    };
+  }
+
+  let packageDir = "";
+  try {
+    packageDir = await resolvePackedPackageDir(extractDir);
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+
+  const manifestPath = path.join(packageDir, "package.json");
+  if (!(await fileExists(manifestPath))) {
+    return { ok: false, error: "extracted package missing package.json" };
+  }
+
+  let manifest: PackageManifest;
+  try {
+    manifest = await readJsonFile<PackageManifest>(manifestPath);
+  } catch (err) {
+    return { ok: false, error: `invalid package.json: ${String(err)}` };
+  }
+
+  let extensions: string[];
+  try {
+    extensions = await ensureClawdbotExtensions(manifest);
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+
+  const pkgName = typeof manifest.name === "string" ? manifest.name : "";
+  const pluginId = pkgName ? unscopedPackageName(pkgName) : "plugin";
+  const targetDir = path.join(extensionsDir, safeDirName(pluginId));
+
+  if (await fileExists(targetDir)) {
+    return {
+      ok: false,
+      error: `plugin already exists: ${targetDir} (delete it first)`,
+    };
+  }
+
+  logger.info?.(`Installing to ${targetDir}…`);
+  await fs.cp(packageDir, targetDir, { recursive: true });
+
+  for (const entry of extensions) {
+    const resolvedEntry = path.resolve(targetDir, entry);
+    if (!(await fileExists(resolvedEntry))) {
+      logger.warn?.(`extension entry not found: ${entry}`);
+    }
+  }
+
+  const deps = manifest.dependencies ?? {};
+  const hasDeps = Object.keys(deps).length > 0;
+  if (hasDeps) {
+    logger.info?.("Installing plugin dependencies…");
+    const npmRes = await runCommandWithTimeout(
+      ["npm", "install", "--omit=dev", "--silent"],
+      { timeoutMs: Math.max(timeoutMs, 300_000), cwd: targetDir },
+    );
+    if (npmRes.code !== 0) {
+      return {
+        ok: false,
+        error: `npm install failed: ${npmRes.stderr.trim() || npmRes.stdout.trim()}`,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    pluginId,
+    targetDir,
+    manifestName: pkgName || undefined,
+    extensions,
+  };
+}
+
+export async function installPluginFromNpmSpec(params: {
+  spec: string;
+  extensionsDir?: string;
+  timeoutMs?: number;
+  logger?: PluginInstallLogger;
+}): Promise<InstallPluginResult> {
+  const logger = params.logger ?? defaultLogger;
+  const timeoutMs = params.timeoutMs ?? 120_000;
+  const spec = params.spec.trim();
+  if (!spec) return { ok: false, error: "missing npm spec" };
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-npm-pack-"));
+  logger.info?.(`Downloading ${spec}…`);
+  const res = await runCommandWithTimeout(["npm", "pack", spec], {
+    timeoutMs: Math.max(timeoutMs, 300_000),
+    cwd: tmpDir,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (res.code !== 0) {
+    return {
+      ok: false,
+      error: `npm pack failed: ${res.stderr.trim() || res.stdout.trim()}`,
+    };
+  }
+
+  const packed = (res.stdout || "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .pop();
+  if (!packed) {
+    return { ok: false, error: "npm pack produced no archive" };
+  }
+
+  const archivePath = path.join(tmpDir, packed);
+  return await installPluginFromArchive({
+    archivePath,
+    extensionsDir: params.extensionsDir,
+    timeoutMs,
+    logger,
+  });
+}

src/plugins/loader.ts

@@ -14,6 +14,7 @@ import type {
   ClawdbotPluginConfigSchema,
   ClawdbotPluginDefinition,
   ClawdbotPluginModule,
+  PluginConfigUiHint,
   PluginDiagnostic,
   PluginLogger,
 } from "./types.js";
@@ -208,6 +209,7 @@ function createPluginRecord(params: {
     cliCommands: [],
     services: [],
     configSchema: params.configSchema,
+    configUiHints: undefined,
   };
 }
 
@@ -307,6 +309,18 @@ export function loadClawdbotPlugins(
     record.description = definition?.description ?? record.description;
     record.version = definition?.version ?? record.version;
     record.configSchema = Boolean(definition?.configSchema);
+    record.configUiHints =
+      definition?.configSchema &&
+      typeof definition.configSchema === "object" &&
+      (definition.configSchema as { uiHints?: unknown }).uiHints &&
+      typeof (definition.configSchema as { uiHints?: unknown }).uiHints ===
+        "object" &&
+      !Array.isArray((definition.configSchema as { uiHints?: unknown }).uiHints)
+        ? ((definition.configSchema as { uiHints?: unknown }).uiHints as Record<
+            string,
+            PluginConfigUiHint
+          >)
+        : undefined;
 
     const validatedConfig = validatePluginConfig({
       schema: definition?.configSchema,

src/plugins/registry.ts

@@ -10,6 +10,7 @@ import type {
   ClawdbotPluginService,
   ClawdbotPluginToolContext,
   ClawdbotPluginToolFactory,
+  PluginConfigUiHint,
   PluginDiagnostic,
   PluginLogger,
   PluginOrigin,
@@ -51,6 +52,7 @@ export type PluginRecord = {
   cliCommands: string[];
   services: string[];
   configSchema: boolean;
+  configUiHints?: Record<string, PluginConfigUiHint>;
 };
 
 export type PluginRegistry = {

src/plugins/types.ts

@@ -11,6 +11,14 @@ export type PluginLogger = {
   error: (message: string) => void;
 };
 
+export type PluginConfigUiHint = {
+  label?: string;
+  help?: string;
+  advanced?: boolean;
+  sensitive?: boolean;
+  placeholder?: string;
+};
+
 export type PluginConfigValidation =
   | { ok: true; value?: unknown }
   | { ok: false; errors: string[] };
@@ -25,6 +33,7 @@ export type ClawdbotPluginConfigSchema = {
   };
   parse?: (value: unknown) => unknown;
   validate?: (value: unknown) => PluginConfigValidation;
+  uiHints?: Record<string, PluginConfigUiHint>;
 };
 
 export type ClawdbotPluginToolContext = {