@withone/cli 2.8.0 → 2.9.0

package/README.md

@@ -265,7 +265,7 @@ one actions find hubspot "find a contact by email" gmail "send an email" --task
 one actions find shopify "list products" -t knowledge
 ```
 
-- 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.
+- 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. Name the platform before every intent, even when they share one (`stripe "list charges" stripe "list refunds"`); a "platform" containing a space is refused as an intent that slipped out of its pair.
 - **`--task`** describes the whole job in one line, in general terms. Agents are asked to send it with every find, since it helps tell similar actions apart.
 - **`-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`), recorded with the find beside the CLI and the harness that launched it, so the account's usage can report which model asked. Agents are asked to send it with every find.
@@ -274,6 +274,8 @@ one actions find shopify "list products" -t knowledge
 
 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.
 
+A platform name no active platform has (`clickup` for `click-up`) is answered with `selector: "unknown_platform"` and a `suggestions` list of the platforms it may have meant, closest first, instead of being searched. Find again with the right name; `one platforms` lists them all.
+
 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.
 
 ### `one actions load <actionId...>`

package/dist/index.js

@@ -3005,6 +3005,9 @@ var EXECUTE_GUIDE = `Run an action with:
 Connection keys come from \`one --agent list\`. Put each value where the action's documentation says it goes: path variables (placeholders like {userId}) in --path-vars, query parameters in --query-params, the request body in -d. Never put path variables or query parameters in -d.`;
 var FindArgsError = class extends Error {
 };
+function misplacedIntent(requests) {
+  return requests.map((r) => r.platform.trim()).find((platform) => /\s/.test(platform));
+}
 function findHint(task, aiModel) {
   const missing = [
     task?.trim() ? null : '--task "<the whole job in one line, in general terms, without names, addresses, IDs or message text>"',
@@ -3063,6 +3066,11 @@ function status(answer, narrowed) {
   if (narrowed.replaced) {
     return "The chosen action is not allowed by this CLI, so this is the next allowed candidate: check it fits before using it.";
   }
+  if (answer.selector === "unknown_platform") {
+    const opening = `No active platform is named \`${answer.platform}\`.`;
+    const suggestions = answer.suggestions ?? [];
+    return suggestions.length === 0 ? `${opening} Check the platform name: \`one platforms\` lists them all.` : `${opening} Did you mean ${suggestions.map((s) => `\`${s}\``).join(", ")}? Find again with the platform you meant.`;
+  }
   if (answer.selector === "none_fit" || answer.selected.length === 0) {
     return answer.alternatives.length === 0 ? "No action fits this intent, and nothing close was found. Rephrase it, or check the platform name." : "No action fits this intent. Rephrase it more specifically, or load one of the alternatives.";
   }
@@ -3105,6 +3113,12 @@ async function find(requests, task, deps, settings, { knowledgeCatalog = false,
   if (empty) {
     throw new FindArgsError("Every request needs a platform and an intent.");
   }
+  const misplaced = misplacedIntent(requests);
+  if (misplaced) {
+    throw new FindArgsError(
+      `"${misplaced}" looks like an intent, not a platform: the pairs are out of step. Name the platform before every intent, e.g. one actions find stripe "list charges" stripe "list refunds".`
+    );
+  }
   const platforms = await reachable(settings, deps);
   const reaches = (platform) => platforms === null || platforms.includes(platform.toLowerCase());
   const asked = requests.filter((r) => reaches(r.platform));
@@ -3181,7 +3195,8 @@ async function find(requests, task, deps, settings, { knowledgeCatalog = false,
       selected,
       alsoSelected: [...deferred, ...plan.deferred.map(ref)],
       ...answer.runnerUp ? { runnerUp: ref(answer.runnerUp) } : {},
-      alternatives: answer.alternatives.map(ref)
+      alternatives: answer.alternatives.map(ref),
+      ...answer.suggestions?.length ? { suggestions: answer.suggestions } : {}
     };
   });
   plans.forEach((plan, index) => {
@@ -3433,7 +3448,9 @@ async function actionsFindCommand(pairs, options) {
     error("--type must be execute or knowledge.");
   }
   if (pairs.length === 0 || pairs.length % 2 !== 0) {
-    error('Pass platform and intent pairs: one actions find <platform> "<intent>" [<platform> "<intent>" ...]');
+    error(
+      'Pass platform and intent pairs, naming the platform before every intent: one actions find <platform> "<intent>" [<platform> "<intent>" ...], e.g. one actions find stripe "list charges" stripe "list refunds"'
+    );
   }
   const requests = [];
   for (let i = 0; i < pairs.length; i += 2) {
@@ -10944,7 +10961,7 @@ Removes a connection by its key. In agent mode, returns \`{"deleted": true, "pla
 one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>" --ai-model "<your model>"
 \`\`\`
 
-One call for the whole task: one platform and intent pair per operation, on any platforms (up to 10). One's decision model picks the action for each and returns it **with its documentation** \u2014 required fields, validation rules, request structure. **Read it before execute.**
+One call for the whole task: one platform and intent pair per operation, on any platforms (up to 10). Name the platform before **every** intent, even when they share one: \`stripe "list charges" stripe "list refunds"\`. One's decision model picks the action for each and returns it **with its documentation** \u2014 required fields, validation rules, request structure. **Read it before execute.**
 
 - **\`intent\` names the operation alone**, in a few words: \`"send a message to a channel"\`, not \`"post 'deploy done' in #eng"\`. IDs, names, and message text in the intent make the search miss.
 - **\`--task\`**: send it with every find. It is the whole job in one line, **in general terms**: what it does, without names, addresses, IDs, or message text. It helps tell similar actions apart.
@@ -10981,7 +10998,8 @@ In \`--agent\` mode:
 - **\`alsoSelected\`** \u2014 also needed, listed rather than documented to keep the answer small: \`actions load\` them.
 - **\`runnerUp\`** \u2014 only when the model was unsure: a **substitute** for the pick. Use one or the other, **never both**.
 - **\`alternatives\`** \u2014 other candidates, undocumented.
-- **\`status\`** \u2014 why: a confidence, *no action fits* (rephrase the intent by outcome, or check the platform), *the decision model was unavailable* (top search result: check it fits), *not allowed by this CLI* (the next allowed candidate stood in), or *allow none of them* (your access settings block the operation \u2014 rephrasing won't help).
+- **\`suggestions\`** \u2014 only when \`selector\` is \`unknown_platform\`: no active platform has the name you sent, so nothing was answered. These are the platforms you may have meant, closest first (\`clickup\` \u2192 \`click-up\`). Find again with the right one; \`one platforms\` lists every name.
+- **\`status\`** \u2014 why: a confidence, *no active platform is named* (use a \`suggestions\` entry, or check \`one platforms\`), *no action fits* (rephrase the intent by outcome, or check the platform), *the decision model was unavailable* (top search result: check it fits), *not allowed by this CLI* (the next allowed candidate stood in), or *allow none of them* (your access settings block the operation \u2014 rephrasing won't help).
 - **\`guide\`** \u2014 how to execute, stated once for every action.
 - \`truncated: false\` means \`knowledge\` is the whole document; small docs are never trimmed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/SKILL.md

@@ -79,7 +79,7 @@ Removes a connection. Returns `{"deleted": true, "platform": "...", "key": "..."
 one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>" --ai-model "<your model>"
 ```
 
-**One call for the whole task**: one platform and intent pair per operation, on any platforms (up to 10). One's decision model picks the action for each and returns it **with its documentation**: exactly what parameters are required, how to structure the request, and where each value goes. Never execute without reading it — without it you'll guess wrong on parameters.
+**One call for the whole task**: one platform and intent pair per operation, on any platforms (up to 10). Name the platform before **every** intent, even when they share one: `stripe "list charges" stripe "list refunds"`. One's decision model picks the action for each and returns it **with its documentation**: exactly what parameters are required, how to structure the request, and where each value goes. Never execute without reading it — without it you'll guess wrong on parameters.
 
 - **`intent` names the operation alone**, in a few words: `"send a message to a channel"`, not `"post 'deploy done' in #eng"`. IDs, names, and message text in the intent make the search miss.
 - **`--task`**: send it with every find. It is the whole job in one line, **in general terms**: `"email a weather report to a contact"`, without names, addresses, IDs, or message text. It helps tell similar actions apart.
@@ -95,7 +95,8 @@ Each entry of `answers[]` carries:
 - `alsoSelected[]` — also needed, listed rather than documented to keep the answer small: `actions load` them.
 - `runnerUp` — only when the model was unsure: a **substitute** for the pick. Use **one or the other, never both**.
 - `alternatives[]` — other candidates, undocumented.
-- `status` — why: a confidence; *no action fits* (rephrase the intent by outcome, or check the platform); *the decision model was unavailable* (the top search result — check it fits); *not allowed by this CLI* (the next allowed candidate stood in); or *allow none of them* (the access settings block the operation — tell the user, rephrasing won't help).
+- `suggestions[]` — only when `selector` is `unknown_platform`: no active platform has the name you sent, so nothing was answered. These are the platforms you may have meant, closest first (`clickup` → `click-up`). Find again with the right one; `one platforms` lists every name.
+- `status` — why: a confidence; *no active platform is named* (use a `suggestions` entry, or check `one platforms`); *no action fits* (rephrase the intent by outcome, or check the platform); *the decision model was unavailable* (the top search result — check it fits); *not allowed by this CLI* (the next allowed candidate stood in); or *allow none of them* (the access settings block the operation — tell the user, rephrasing won't help).
 
 `guide` (once, at the end) says how to execute any of them.