@vibeframe/cli 0.109.2 → 0.111.0

package/dist/tools/_shared/elicit.d.ts

@@ -0,0 +1,31 @@
+import type { ElicitForm } from "../adapters/mcp.js";
+/**
+ * @module tools/_shared/elicit
+ *
+ * Pre-flight elicitation for the `build` tool: when an MCP client supports
+ * elicitation, ask the user the choices the host agent would otherwise pick
+ * silently (narration provider, paid backdrop generation, cost ceiling).
+ * Pure functions — the MCP wiring lives in the tool's execute and the
+ * server's makeElicitFn; CLI/Agent surfaces never reach this code path.
+ */
+/** The subset of build args that drive the question set. */
+export interface BuildChoiceArgs {
+    stage?: "assets" | "compose" | "sync" | "render" | "all";
+    ttsProvider?: "auto" | "elevenlabs" | "kokoro";
+    skipNarration?: boolean;
+    skipBackdrop?: boolean;
+    imageProvider?: string;
+    maxCostUsd?: number;
+}
+/**
+ * Builds the elicitation form for a build call, asking ONLY about choices the
+ * caller left unspecified. Returns null when there is nothing to ask — every
+ * choice explicit, or the requested stage doesn't generate assets.
+ */
+export declare function planBuildElicitation(args: BuildChoiceArgs): ElicitForm | null;
+/**
+ * Maps accepted form answers back onto build args. Unknown or invalid values
+ * are ignored so a misbehaving client can never produce a worse state than
+ * the defaults the user would have gotten without elicitation.
+ */
+export declare function applyElicitationAnswers<T extends BuildChoiceArgs>(args: T, content: Record<string, string | number | boolean | string[]> | undefined): T;

package/dist/tools/_shared/elicit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/adapters/mcp.d.ts

@@ -17,11 +17,40 @@ export interface McpInputSchema {
     required: string[];
     description?: string;
 }
+/** MCP spec ToolAnnotations — safety hints surfaced to hosts. */
+export interface McpToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint: boolean;
+}
 export interface McpTool {
     name: string;
+    /** Human-readable display name (MCP BaseMetadata.title). */
+    title: string;
     description: string;
     inputSchema: McpInputSchema;
+    annotations: McpToolAnnotations;
+}
+/**
+ * Structural mirror of the MCP elicitation form request/result (the CLI
+ * package deliberately has no dependency on @modelcontextprotocol/sdk).
+ * `requestedSchema.properties` values follow the spec's flat primitive
+ * schema: string (optionally with enum/enumNames), number, boolean.
+ */
+export interface ElicitForm {
+    message: string;
+    requestedSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
 }
+export interface ElicitOutcome {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]>;
+}
+export type ElicitFn = (form: ElicitForm) => Promise<ElicitOutcome>;
 /** Per-call extras forwarded by the MCP server request handler. */
 export interface McpCallExtra {
     /**
@@ -34,6 +63,12 @@ export interface McpCallExtra {
         total?: number;
         message?: string;
     }) => void;
+    /**
+     * Sends an `elicitation/create` form to the client and resolves with the
+     * user's answer. Only present when the connected client advertises the
+     * elicitation capability.
+     */
+    elicit?: ElicitFn;
 }
 export type McpDispatcher = (name: string, args: Record<string, unknown>, extra?: McpCallExtra) => Promise<{
     content: Array<{

package/dist/tools/adapters/mcp.js

@@ -211,16 +211,29 @@ function manifestToMcpTools(manifest) {
     const inputSchema = zodToJsonSchema(t.schema);
     return {
       name: t.name,
+      title: t.title,
       description: t.description,
       inputSchema: {
         type: "object",
         properties: inputSchema.properties ?? {},
         required: inputSchema.required ?? [],
         ...inputSchema.description ? { description: inputSchema.description } : {}
-      }
+      },
+      annotations: toMcpAnnotations(t.annotations)
     };
   });
 }
+function toMcpAnnotations(a) {
+  if (a.readOnly) {
+    return { readOnlyHint: true, openWorldHint: a.openWorld };
+  }
+  return {
+    readOnlyHint: false,
+    destructiveHint: a.destructive ?? true,
+    ...a.idempotent !== void 0 ? { idempotentHint: a.idempotent } : {},
+    openWorldHint: a.openWorld
+  };
+}
 function buildMcpDispatcher(manifest) {
   const byName = /* @__PURE__ */ new Map();
   for (const t of manifest) {
@@ -245,7 +258,8 @@ function buildMcpDispatcher(manifest) {
         () => tool.execute(parsed.data, {
           workingDirectory: process.cwd(),
           surface: "mcp",
-          ...extra?.onProgress ? { onProgress: sink.send } : {}
+          ...extra?.onProgress ? { onProgress: sink.send } : {},
+          ...extra?.elicit ? { elicit: extra.elicit } : {}
         })
       );
       const text = result.success ? JSON.stringify({ success: true, ...result.data }) : result.data ? JSON.stringify({

package/dist/tools/define-tool.d.ts

@@ -49,6 +49,23 @@ export interface ExecuteContext {
         total?: number;
         message?: string;
     }) => void;
+    /**
+     * Optional MCP elicitation channel. Present only when the connected MCP
+     * client advertises the elicitation capability; CLI/Agent surfaces leave
+     * it undefined, so CLI behavior never changes. See adapters/mcp.ts for
+     * the structural types.
+     */
+    elicit?: (form: {
+        message: string;
+        requestedSchema: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required?: string[];
+        };
+    }) => Promise<{
+        action: "accept" | "decline" | "cancel";
+        content?: Record<string, string | number | boolean | string[]>;
+    }>;
 }
 export interface ToolExecuteResult {
     success: boolean;
@@ -71,6 +88,32 @@ export interface ToolDefinition<S extends ZodTypeAny = ZodTypeAny> {
     replacement?: string;
     /** Short explanation for product-surface routing. */
     note?: string;
+    /**
+     * Human-readable display name shown by MCP hosts, e.g. "Add Clip to
+     * Timeline". Required by the Anthropic extension directory.
+     */
+    title: string;
+    /**
+     * MCP safety annotations (directory requirement: every tool declares
+     * readOnlyHint or destructiveHint).
+     * - `readOnly: true` — the tool never modifies files or project state.
+     * - `readOnly: false` — the tool writes; `destructive` defaults to true
+     *   (may overwrite/modify existing data), set false for purely additive
+     *   tools; `idempotent: true` when re-running with identical args has no
+     *   additional effect.
+     * - `openWorld` — true when the tool calls external provider APIs; false
+     *   for purely local work (ffmpeg, filesystem). Always stated explicitly
+     *   because the MCP spec default is true.
+     */
+    annotations: {
+        readOnly: true;
+        openWorld: boolean;
+    } | {
+        readOnly: false;
+        destructive?: boolean;
+        idempotent?: boolean;
+        openWorld: boolean;
+    };
     /** Identical for MCP description and Agent description. One paragraph. */
     description: string;
     /** Single source of truth for argument shape. Must be a `z.object({...})`. */