@withone/cli 2.7.0 → 2.8.0

package/README.md

@@ -266,9 +266,10 @@ 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.
-- **`--task`** describes the whole job in one line, in general terms, which helps choose between similar actions.
+- **`--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.
+- **`--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,14 @@ 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 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}\``;
 }
@@ -3444,13 +3452,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");
@@ -10804,7 +10815,7 @@ Find the actions a task needs with their docs, in one call, then execute them. T
 \`\`\`bash
 one --agent connection list                                    # See connected platforms + your access on each
 one --agent connection delete <connection-key>                 # Remove a connection
-one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>"  # Find every action, with its docs (READ them)
+one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>" --ai-model "<your model>"  # Find every action, with its docs (READ them)
 one --agent actions load <actionId> --section "<name>"          # More of a doc: a section it left out, --full, --toc
 one --agent actions execute <platform> <actionId> <key> -d '{}'  # Execute it
 \`\`\`
@@ -10930,15 +10941,16 @@ Removes a connection by its key. In agent mode, returns \`{"deleted": true, "pla
 ### 2. Find Actions
 
 \`\`\`bash
-one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>"
+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.**
 
 - **\`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\`** (optional) is the whole job in one line, **in general terms**: what it does, without names, addresses, IDs, or message text. It helps choose between similar actions.
+- **\`--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\`** (optional) names the model running the CLI (e.g. \`claude-sonnet-5\`); it is recorded with the find so the account's usage can report which model asked.
+- **\`--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:
@@ -13246,7 +13258,7 @@ program.command("platforms").alias("p").description("List available platforms").
   await platformsCommand(options);
 });
 var actions = program.command("actions").alias("a").description("Find, read, and execute platform actions (workflow: find \u2192 execute)");
-actions.command("find <pairs...>").alias("f").description('Find the action for every operation a task needs, across platforms, with its documentation, in one call: one actions find <platform> "<intent>" [<platform> "<intent>" ...] (up to 10 pairs). Each intent names the operation alone ("send an email"), without its data. Large documents come back as a digest; each names the exact `actions load` command for what it left out').option("--task <task>", 'The whole task in one line, in general terms (e.g. "email a report to a contact"): what it does, without names, addresses, IDs or message text. Helps choose between similar actions').option("-t, --type <type>", "execute (default: actions to run now) or knowledge (the catalog for writing code and building flows and relays, with the platform's own endpoints). Knowledge-only mode always uses knowledge").option("--ai-model <model>", "The AI model you are running as (e.g. claude-sonnet-5), recorded with this find so the account's usage can report which model asked. Optional").option("--no-cache", "Bypass the cache for action documentation and re-fetch it (the fresh response still refreshes the cache)").option("--no-knowledge", "List the chosen actions (actionId, title, method, path) without their documentation; load it with `one actions load <actionId>`").action(async (pairs, options) => {
+actions.command("find <pairs...>").alias("f").description('Find the action for every operation a task needs, across platforms, with its documentation, in one call: one actions find <platform> "<intent>" [<platform> "<intent>" ...] (up to 10 pairs). Each intent names the operation alone ("send an email"), without its data. Large documents come back as a digest; each names the exact `actions load` command for what it left out').option("--task <task>", 'The whole task in one line, in general terms (e.g. "email a report to a contact"): what it does, without names, addresses, IDs or message text. Send it with every find: it helps tell similar actions apart').option("-t, --type <type>", "execute (default: actions to run now) or knowledge (the catalog for writing code and building flows and relays, with the platform's own endpoints). Knowledge-only mode always uses knowledge").option("--ai-model <model>", "Your model name as you know it (e.g. claude-sonnet-5), recorded with this find. Send it with every find; leave it out only if you do not know which model you are").option("--no-cache", "Bypass the cache for action documentation and re-fetch it (the fresh response still refreshes the cache)").option("--no-knowledge", "List the chosen actions (actionId, title, method, path) without their documentation; load it with `one actions load <actionId>`").action(async (pairs, options) => {
   await actionsFindCommand(pairs, options);
 });
 actions.command("load <actionIds...>").alias("l").description("More of an action's documentation (up to 10 actions): the digest by default, --section for one a digest left out, --full for the whole document, --toc for its contents. Also how to read an alternative from a find answer").option("--section <name>", 'Return only the named section(s) \u2014 by heading, id, or alias (e.g. "Response Fields", response, optional). Repeatable or comma-separated', collect, []).option("--full", "Return the whole document instead of the digest").option("--toc", "List every section (id, heading, size) without the document").option("--no-cache", "Bypass the cache and re-fetch from the API (the fresh response still refreshes the cache)").option("--cache-status", "Print cache metadata without fetching").action(async (actionIds, options) => {

package/package.json

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

package/skills/one/SKILL.md

@@ -76,15 +76,16 @@ Removes a connection. Returns `{"deleted": true, "platform": "...", "key": "..."
 ### 2. Find every action the task needs, with its docs (READ them before executing)
 
 ```bash
-one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --task "<the job, in general terms>"
+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.
 
 - **`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`** (optional) 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 choose between similar actions.
+- **`--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`** (optional): the model you are running as (e.g. `claude-sonnet-5`), recorded with the find so the account's usage can report which model asked.
+- **`--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`.