@withone/cli 1.57.1 → 2.1.0

package/README.md

@@ -64,18 +64,15 @@ one add gmail
 # See what you're connected to
 one list
 
-# Search for actions you can take
-one actions search gmail "send email" -t execute
-
-# Read the docs for an action
-one actions knowledge gmail <actionId>
+# Find the action, with its docs
+one actions find gmail "send an email" --task "email a hello to a contact"
 
 # Execute it
 one actions execute gmail <actionId> <connectionKey> \
   -d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'
 ```
 
-That's it. Five commands to go from zero to sending an email through Gmail's API - fully authenticated, correctly formatted, without touching a single OAuth token.
+That's it. Four commands to go from zero to sending an email through Gmail's API - fully authenticated, correctly formatted, without touching a single OAuth token.
 
 ### Multi-step flows
 
@@ -210,7 +207,7 @@ You need the connection key (rightmost column) when executing actions.
 | `{"policy": "methods", "methods": ["GET"]}` | Only actions with those HTTP methods | Permission level is `read` or `write` |
 | `{"policy": "actions", "actions": [{"actionId": "...", "title": "...", "method": "..."}]}` | Only these specific actions | An action allowlist is configured |
 
-An action allowlist wins over the permission level (and is then method-filtered by it). When the policy is `actions`, those actions are exactly what may run — no `actions search` needed.
+An action allowlist wins over the permission level (and is then method-filtered by it). When the policy is `actions`, those actions are exactly what may run — `actions load <actionId>` reads their docs, no find needed.
 
 ```jsonc
 // one --agent list
@@ -258,39 +255,38 @@ one platforms -c "CRM"     # filter by category
 one platforms --json       # machine-readable output
 ```
 
-### `one actions search <platform> <query>`
+### `one actions find <platform> <intent> [<platform> <intent> ...]`
 
-Search for API actions on a connected platform using natural language.
+Find the action for every operation a task needs, across platforms, **with its documentation**, in one call: parameters, validation rules, request/response structure, and platform-specific quirks. One's decision model picks the action for each intent.
 
 ```bash
-one actions search shopify "list products"
-one actions search hubspot "create contact" -t execute
-one actions search gmail "send email"
+one actions find gmail "send an email"
+one actions find hubspot "find a contact by email" gmail "send an email" --task "email a follow-up to a CRM contact"
+one actions find shopify "list products" -t knowledge
 ```
 
-Returns the top 5 matching actions with their action IDs, HTTP methods, and paths. Use `-t execute` when you intend to run the action, or `-t knowledge` (default) when you want to learn about it or write code against it.
-
-### `one actions knowledge <platform> <actionId>`
+- Each **intent** names the operation alone, in a few words (`"send a message to a channel"`), without its data: IDs, names and message text make the search miss. Up to 10 pairs.
+- **`--task`** describes the whole job in one line, in general terms, which helps choose between similar actions.
+- **`-t knowledge`** searches the catalog for writing code and building flows and relays, which includes the platform's own (passthrough) endpoints; the default is the catalog for running actions now.
+- **`--ai-model`** names the model running the CLI (e.g. `claude-sonnet-5`), for tuning documentation per model later.
+- **`--no-knowledge`** lists the chosen actions (actionId, title, method, path) without fetching their documentation; load it later with `one actions load <actionId>`.
 
-Get the full documentation for an action - parameters, validation rules, request/response structure, examples, and the exact API request format.
+Each intent's answer gives the action(s) to use with their docs, any actions also needed beside them, a **substitute** when the model was unsure (use one or the other, never both), and a few alternatives, then says once how to execute. Always read the docs before executing. The access settings from `one config` apply: an action they refuse is never offered.
 
-```bash
-one actions knowledge shopify 67890abcdef
-```
+Large documents come back as a **digest**: request-building sections in full (method/URL, headers, description, enforcement rules, required and optional parameters, sample request, gotchas, error handling), then a notice naming what was left out with the exact command to load it. In knowledge-only mode each pick comes back whole, with how to call it from code.
 
-Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
+### `one actions load <actionId...>`
 
-In `--agent` mode the response is a **digest**: request-building sections in full (method/URL, headers, description, enforcement rules, required and optional parameters, sample request, gotchas, error handling) plus a table of contents for the rest. Response shapes, response-field tables, and worked examples — the bulk of every large doc — are loaded on demand:
+More of an action's documentation: the digest by default (how to read an alternative from a find answer), or a section a digest left out, the whole document, or its table of contents. Up to 10 action ids.
 
 ```bash
-one --agent actions knowledge github <actionId>                              # digest + sections[] table of contents
-one --agent actions knowledge github <actionId> --section "Response Fields"  # one section, by heading or id
-one --agent actions knowledge github <actionId> --section response,examples  # several, by alias
-one --agent actions knowledge github <actionId> --full                       # whole document
-one --agent actions knowledge github <actionId> --toc                        # every section id, no document
+one --agent actions load <actionId> --section "Response Fields"  # one section, by heading or id
+one --agent actions load <actionId> --section response,examples  # several, by alias
+one --agent actions load <actionId> --full                       # whole document
+one --agent actions load <actionId> --toc                        # every section id, no document
 ```
 
-The JSON carries `truncated`, `sections[]` (the omitted sections: id, heading, chars), and `more` (the commands to load the rest); the markdown ends with the same notice so it is never mistaken for the complete doc. Small documents are returned whole. Section requests are served from the local cache. Human (non-agent) output always prints the full document; `--section` works there too.
+Loads are served from the local cache once a doc is cached.
 
 ### `one actions execute <platform> <actionId> <connectionKey>`
 
@@ -351,7 +347,7 @@ Agent-mode output includes `parallel: true`, per-action `status`/`durationMs`/`r
 
 ### `one cache`
 
-Manage the local cache for knowledge and search responses. The CLI automatically caches `actions knowledge` and `actions search` results so repeated calls serve instantly from disk. `actions execute` reuses the cached action details (method, path, validation schema) for its preflight lookup, so a knowledge call followed by execute costs a single API round trip.
+Manage the local cache of action documentation. `actions find` and `actions load` read each action's details (docs, method, path, validation schema) through the cache, so repeated reads serve instantly from disk, and `actions execute` reuses them for its preflight lookup, so a find followed by execute costs a single API round trip for the execute.
 
 ```bash
 one cache list                    # List all cached entries with age and status
@@ -361,13 +357,13 @@ one cache clear <actionId>        # Clear a specific entry
 one cache update-all              # Re-fetch fresh data for all cached entries
 ```
 
-Knowledge and search commands also support cache flags:
+Find, load and execute also support cache flags:
 
 ```bash
-one actions knowledge gmail <actionId> --no-cache       # Skip cache, fetch fresh
-one actions knowledge gmail <actionId> --cache-status   # Check cache status
-one actions knowledge gmail <actionId> --section response   # Served from the cached doc, no fetch
-one actions search gmail "send email" --no-cache        # Skip cache for search
+one actions find gmail "send an email" --no-cache       # Fetch the docs fresh
+one actions load <actionId> --no-cache                  # Skip cache, fetch fresh
+one actions load <actionId> --cache-status              # Check cache status
+one actions load <actionId> --section response          # Served from the cached doc, no fetch
 one actions execute gmail <actionId> <key> --no-cache   # Fresh action-details lookup
 ```
 
@@ -739,8 +735,7 @@ The power of One is in the workflow. Every interaction follows the same pattern:
 
 ```
 one list                    → What am I connected to?
-one actions search          → What can I do?
-one actions knowledge       → How do I do it?
+one actions find            → What do I run, and how?
 one actions execute         → Do it.
 ```
 
@@ -749,7 +744,7 @@ This is the same workflow whether you're sending emails, creating CRM contacts,
 For multi-step workflows that chain actions across platforms:
 
 ```
-one actions knowledge       → Learn each action's schema
+one actions find            → Find each action, with its schema
 one flow create             → Define the workflow as JSON
 one flow validate           → Check it
 one flow execute            → Run it
@@ -766,11 +761,10 @@ If you're an AI agent using the One MCP server, the tools map directly:
 | MCP Tool | CLI Command |
 |----------|------------|
 | `list_one_integrations` | `one list` + `one platforms` |
-| `search_one_platform_actions` | `one actions search` |
-| `get_one_action_knowledge` | `one actions knowledge` |
+| `find_one_actions` | `one actions find` (and `one actions load` for its `load`) |
 | `execute_one_action` | `one actions execute` |
 
-The workflow is the same: list → search → knowledge → execute. Never skip the knowledge step - it contains required parameter info and platform-specific details that are critical for building correct requests.
+The workflow is the same: list → find → execute. Never execute without reading the docs find returns - they contain required parameter info and platform-specific details that are critical for building correct requests.
 
 ## MCP server installation
 

package/dist/{chunk-QCXFSOTS.js → chunk-6EQDEYVD.js}

@@ -211,6 +211,19 @@ var OneApi = class {
     });
     return response || [];
   }
+  /**
+   * The action for each intent, across platforms, in one call: search plus
+   * One's decision model, which picks among the candidates. Core caps a call
+   * at 10 intents and refuses more with a 400 naming the cap.
+   */
+  async findActions(requests, task, knowledgeAgent) {
+    const response = await this.requestFull({
+      path: "/available-actions/find",
+      method: "POST",
+      body: { requests, ...task ? { task } : {}, knowledgeAgent }
+    });
+    return Array.isArray(response) ? response : [];
+  }
   async getActionDetails(actionId) {
     const response = await this.requestFull({
       path: "/knowledge",
@@ -222,19 +235,6 @@ var OneApi = class {
     }
     return actions[0];
   }
-  async getActionKnowledge(actionId) {
-    const action = await this.getActionDetails(actionId);
-    if (!action.knowledge || !action.method) {
-      return {
-        knowledge: "No knowledge was found",
-        method: "No method was found"
-      };
-    }
-    return {
-      knowledge: action.knowledge,
-      method: action.method
-    };
-  }
   async requestWithMeta(opts) {
     let url = `${this.apiBase}${opts.path}`;
     if (opts.queryParams && Object.keys(opts.queryParams).length > 0) {
@@ -290,27 +290,6 @@ var OneApi = class {
     }
     return { data: actions[0], etag: result.etag, status: result.status };
   }
-  async searchActionsWithMeta(platform, query, agentType, ifNoneMatch) {
-    const isKnowledgeAgent = agentType === "knowledge";
-    const queryParams = {
-      query,
-      limit: "5"
-    };
-    if (isKnowledgeAgent) {
-      queryParams.knowledgeAgent = "true";
-    } else {
-      queryParams.executeAgent = "true";
-    }
-    const result = await this.requestWithMeta({
-      path: `/available-actions/search/${platform}`,
-      queryParams,
-      ifNoneMatch
-    });
-    if (result.status === 304) {
-      return { data: null, etag: result.etag, status: 304 };
-    }
-    return { data: result.data || [], etag: result.etag, status: result.status };
-  }
   async executePassthroughRequest(args, preloadedAction) {
     const action = preloadedAction ?? await this.getActionDetails(args.actionId);
     const method = action.method;
@@ -555,11 +534,6 @@ var PERMISSION_METHODS = {
   write: ["GET", "POST", "PUT", "PATCH"],
   admin: null
 };
-function filterByPermissions(actions, permissions) {
-  const allowed = PERMISSION_METHODS[permissions];
-  if (allowed === null) return actions;
-  return actions.filter((a) => allowed.includes(a.method.toUpperCase()));
-}
 function isMethodAllowed(method, permissions) {
   const allowed = PERMISSION_METHODS[permissions];
   if (allowed === null) return true;
@@ -568,32 +542,6 @@ function isMethodAllowed(method, permissions) {
 function isActionAllowed(actionId, allowedActionIds) {
   return allowedActionIds.includes("*") || allowedActionIds.includes(actionId);
 }
-function buildActionKnowledgeWithGuidance(knowledge, method, platform, actionId) {
-  return `CLI EXECUTION GUIDE (read this FIRST)
-========================================
-To execute this action, use the One CLI with SEPARATE flags for each parameter type.
-Do NOT pass path variables or query parameters in the -d body flag \u2014 this causes 403 errors.
-
-PARAMETER \u2192 FLAG MAPPING:
-- Path variables (URL placeholders like {userId}, {id}) \u2192 --path-vars '{"userId": "me"}'
-- Query parameters (filtering, pagination, format) \u2192 --query-params '{"key": "value"}'
-  - For repeated params, use arrays: --query-params '{"metadataHeaders": ["From", "Subject"]}'
-- Request body (POST/PUT/PATCH payload) \u2192 -d '{"field": "value"}'
-
-EXAMPLE:
-one --agent actions execute ${platform} ${actionId} <connectionKey> \\
-  --path-vars '{ ... }' \\
-  --query-params '{ ... }' \\
-  -d '{ ... }'
-
-Omit any flag not needed (e.g., omit --path-vars if URL has no placeholders, omit -d for GET).
-
-Read the API documentation below to identify which parameters are path variables, query parameters, or body fields, then map them to the correct flags above.
-
-========================================
-
-${knowledge}`;
-}
 
 // src/lib/cache.ts
 import fs from "fs";
@@ -601,7 +549,7 @@ import path from "path";
 function knowledgeDir() {
   return path.join(homeDir(), ".one", "cache", "knowledge");
 }
-function searchDir() {
+function legacySearchDir() {
   return path.join(homeDir(), ".one", "cache", "search");
 }
 function sanitizeFilename(input) {
@@ -610,10 +558,6 @@ function sanitizeFilename(input) {
 function knowledgeCachePath(actionId) {
   return path.join(knowledgeDir(), `${sanitizeFilename(actionId)}.json`);
 }
-function searchCachePath(platform, query, type) {
-  const key = `${platform}_${sanitizeFilename(query)}_${type || "knowledge"}`;
-  return path.join(searchDir(), `${key}.json`);
-}
 function readCache(filePath) {
   try {
     const content = fs.readFileSync(filePath, "utf-8");
@@ -638,16 +582,6 @@ function isFresh(entry) {
 function getAge(entry) {
   return Math.floor((Date.now() - new Date(entry.cachedAt).getTime()) / 1e3);
 }
-function buildCacheMeta(entry, hit) {
-  if (!entry) {
-    return { hit: false, age: 0, fresh: false };
-  }
-  return {
-    hit,
-    age: getAge(entry),
-    fresh: isFresh(entry)
-  };
-}
 function formatAge(seconds) {
   if (seconds < 60) return `${seconds}s`;
   if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
@@ -662,25 +596,22 @@ function formatAge(seconds) {
 }
 function listCacheEntries() {
   const entries = [];
-  for (const [dir, type] of [[knowledgeDir(), "knowledge"], [searchDir(), "search"]]) {
-    try {
-      const files = fs.readdirSync(dir);
-      for (const file of files) {
-        if (!file.endsWith(".json")) continue;
-        const filePath = path.join(dir, file);
-        const entry = readCache(filePath);
-        if (entry) {
-          entries.push({ type, filePath, entry });
-        }
+  try {
+    for (const file of fs.readdirSync(knowledgeDir())) {
+      if (!file.endsWith(".json")) continue;
+      const filePath = path.join(knowledgeDir(), file);
+      const entry = readCache(filePath);
+      if (entry) {
+        entries.push({ type: "knowledge", filePath, entry });
       }
-    } catch {
     }
+  } catch {
   }
   return entries;
 }
 function clearAll() {
   let count = 0;
-  for (const dir of [knowledgeDir(), searchDir()]) {
+  for (const dir of [knowledgeDir(), legacySearchDir()]) {
     try {
       const files = fs.readdirSync(dir);
       for (const file of files) {
@@ -821,7 +752,7 @@ var FLOW_SCHEMA = {
       description: "Execute a platform API action",
       fields: {
         platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
-        actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
+        actionId: { type: "string", required: true, description: "Action ID from `actions find`" },
         connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
         connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
         data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
@@ -1209,7 +1140,7 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
 
 1. **Design first** \u2014 clarify the end goal, map the full value chain, identify where AI analysis is needed
 2. **Discover connections** \u2014 \`one --agent connection list\`
-3. **Get knowledge** for every action \u2014 \`one --agent actions knowledge <platform> <actionId>\`
+3. **Find every action with its docs** \u2014 \`one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...]\`, and \`actions load <actionId>\` for more
 4. **Construct JSON** \u2014 declare inputs, wire steps with selectors
 5. **Validate** \u2014 \`one --agent flow validate <key>\`
 6. **Execute** \u2014 \`one --agent flow execute <key> -i param=value\``);
@@ -1534,7 +1465,7 @@ For flows that still use literal \`connectionKey\` strings via inputs, an input
 }
 \`\`\`
 
-Note: Action IDs above are placeholders. Always use \`one --agent actions search <platform> "<query>"\` to find real IDs.
+Note: Action IDs above are placeholders. Always use \`one --agent actions find <platform> "<intent>"\` to find real IDs.
 
 ## AI-Augmented Pattern
 
@@ -1549,7 +1480,7 @@ Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, n
 ## Notes
 
 - Connection keys are **inputs**, not hardcoded
-- Action IDs in examples are placeholders \u2014 always use \`actions search\`
+- Action IDs in examples are placeholders \u2014 always use \`actions find\`
 - Inline \`code.source\` steps allow \`require('crypto' | 'buffer' | 'url' | 'path')\` \u2014 \`fs\`, \`http\`, \`child_process\` are blocked
 - For anything beyond one-liners, use \`code.module\` to point at a \`.mjs\` file in the flow's \`lib/\` folder \u2014 runs as a child \`node\` process with full Node APIs, reads \`$\` from stdin, writes JSON to stdout
 - Bash steps require \`--allow-bash\` flag
@@ -2354,7 +2285,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-QQ675PJD.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-L3JG2WCY.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -3274,17 +3205,13 @@ export {
   OneApi,
   TimeoutError,
   PERMISSION_METHODS,
-  filterByPermissions,
   isMethodAllowed,
   isActionAllowed,
-  buildActionKnowledgeWithGuidance,
   knowledgeCachePath,
-  searchCachePath,
   readCache,
   writeCache,
   isFresh,
   getAge,
-  buildCacheMeta,
   formatAge,
   listCacheEntries,
   clearAll,

package/dist/{flow-runner-QQ675PJD.js → flow-runner-L3JG2WCY.js}

@@ -12,7 +12,7 @@ import {
   stripStepsAlias,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-QCXFSOTS.js";
+} from "./chunk-6EQDEYVD.js";
 import "./chunk-44CV5IMX.js";
 import "./chunk-6UB623BG.js";
 export {