@withone/cli 2.7.1 → 2.8.1

package/README.md

@@ -265,10 +265,11 @@ 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.
+- An answer to a find without `--task` or `--ai-model` carries a `hint` field (a dim line for humans) asking for them on the next find. Both stay optional.
 - **`--no-knowledge`** lists the chosen actions (actionId, title, method, path) without fetching their documentation; load it later with `one actions load <actionId>`.
 
 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.

package/dist/index.js

@@ -3005,6 +3005,17 @@ 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>"',
+    aiModel?.trim() ? null : '--ai-model "<your model name>"'
+  ].filter((m) => m !== null);
+  if (missing.length === 0) return void 0;
+  return `Send ${missing.join(" and ")} with every find: the task helps tell similar actions apart, and both are recorded with the find.`;
+}
 function actionHeading(action) {
   return `${action.title} \xB7 \`${action.method.toUpperCase()} ${action.path}\` \xB7 actionId: \`${action.actionId}\``;
 }
@@ -3097,6 +3108,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));
@@ -3425,7 +3442,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) {
@@ -3444,13 +3463,16 @@ async function actionsFindCommand(pairs, options) {
       settings,
       { knowledgeCatalog: options.type === "knowledge", knowledge: options.knowledge !== false }
     );
+    const hint = findHint(options.task, options.aiModel);
     if (isAgentMode()) {
-      json(result);
+      json(hint ? { ...result, hint } : result);
       return;
     }
     spinner.stop("Found");
     console.log();
     console.log(renderFind(result));
+    if (hint) console.log(`
+${pc7.dim(hint)}`);
     console.log();
   } catch (error2) {
     spinner.stop("Find failed");
@@ -10933,12 +10955,13 @@ 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.
 - **\`-t knowledge\`** searches the catalog for writing code and building flows and relays, which includes the platform's own (passthrough) endpoints; the default, \`-t execute\`, is the catalog for running actions now. Knowledge-only mode always uses \`knowledge\`.
 - **\`--ai-model\`**: send it with every find. Your model name as you know it (e.g. \`claude-sonnet-5\`), recorded with the find; leave it out only if you do not know which model you are.
+- A find answer sent without either carries a **\`hint\`** naming what was missing: add it on your next find.
 - **\`--no-knowledge\`** (optional) lists the chosen actions without their documentation, when only the actionIds are needed. Load the documentation with \`actions load\` before executing.
 
 In \`--agent\` mode:

package/package.json

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

package/skills/one/SKILL.md

@@ -79,12 +79,13 @@ 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.
 - **`-t knowledge`** searches the catalog for writing code and building flows and relays (it includes the platform's own passthrough endpoints); the default, `-t execute`, is the catalog for running actions now.
 - **`--ai-model`**: send it with every find. Your model name as you know it (e.g. `claude-sonnet-5`), recorded with the find; leave it out only if you do not know which model you are.
+- A find answer sent without either carries a **`hint`** naming what was missing: add it on your next find.
 - **`--no-knowledge`** (optional): list the chosen actions without their documentation, when you only need the actionIds. Load the documentation with `actions load` before executing.
 - Platform names are lowercase; multi-word names use dashes: `gmail`, `hubspot`, `ship-station`, `google-calendar`.