@kosuke-ai/kosuke 1.0.132 → 1.0.133

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.133
4
+
5
+ - When stdout is a pipe, a short list's footer (`20 of 3122. More: --cursor <c>`) goes inside the JSON as `meta.hint`, notices as `meta.notices`, and `integrations call` and `integrations request` name the connection they ran on as `meta.ranOn` in a JSON object result, so `kosuke ... 2>&1 | jq` reads one JSON value. A terminal still shows these lines on stderr, and errors still go to stderr with a non-zero exit. A flag given to the wrong form of a command now names the form that takes it and the closest flag of this form.
6
+
3
7
  ## 1.0.132
4
8
 
5
9
  - Add `kosuke sensei threads search`, which finds the messages of one of your Sensei Threads that hold some words, newest first, each with a snippet. `kosuke sensei threads get --around <messageId>` reads the replies around one, such as a search hit. `kosuke user profile get` now includes your Thread routing setting (`threadRouting`: off, ask or automatic).
package/README.md CHANGED
@@ -23,7 +23,9 @@ for its whole answer by name: pass it in anything that pipes into `jq`.
23
23
  The lists are short by default: `projects list`, `sessions list`, `tasks list`, `crons list`,
24
24
  `activity list`, `sensei threads list`, `sensei cards list` and `files list` print at most 20
25
25
  rows, each with the fields you pick a row by and no null ones, and end with a line on stderr
26
- such as `20 of 3122. More: --cursor <c>`. `--all` reads every page, `--full` keeps every field,
26
+ such as `20 of 3122. More: --cursor <c>`. When stdout is a pipe that line goes in the JSON
27
+ instead, as `meta.hint`, with any notice in `meta.notices`, so `2>&1 | jq` still reads one value;
28
+ stderr then holds only errors. `--all` reads every page, `--full` keeps every field,
27
29
  `--fields` picks from whole rows, and `get` prints one whole. `--json` prints and sends exactly what it did before.
28
30
 
29
31
  Path params are positional, request fields are flags (`--exclude-archived`,
@@ -228,8 +230,10 @@ account, short id) and how many read-only and write tools it has. `--toolkit` an
228
230
  and how to narrow it. `--account` takes a connection's alias such as
229
231
  `notion-personal`, its short id or `scope:label`; case, curly quotes and extra
230
232
  spaces do not matter, and it is needed when several connections can run a tool.
231
- `call` prints the tool's text on stdout and the connection it ran on on stderr,
232
- and exits 1 when the tool reports an error. A tool's file argument takes a file
233
+ `call` prints the tool's text on stdout and the connection it ran on on stderr;
234
+ when stdout is a pipe, a JSON object result carries the connection as `meta.ranOn`
235
+ instead (`alias`, `scope`, `label`, `account`), and nothing else goes on stderr. It
236
+ exits 1 when the tool reports an error. A tool's file argument takes a file
233
237
  reference: `--file <argument>=<path>` uploads the local file and fills it in,
234
238
  once per file, and a file inside a list or object names its path, such as
235
239
  `attachment.0`. The file goes straight to storage, up to 5 GiB.
@@ -45,7 +45,8 @@ export function attachIntegrationsRequest(root, runtime, { guarded, fail, report
45
45
  leafAt(root, HAND_WRITTEN.integrationsRequest.command)
46
46
  .description("Send one request straight to a Composio toolkit's own API through your connection, for an " +
47
47
  'action no listed tool does, and print its answer. Composio adds the credentials on the ' +
48
- 'server, so no token is needed or shown. The connection it ran on is named on stderr. ' +
48
+ 'server, so no token is needed or shown. The connection it ran on is named on stderr at a ' +
49
+ 'terminal; piped, a JSON object answer carries it as meta.ranOn. ' +
49
50
  'A refusal or a vendor error exits 1.')
50
51
  .argument('<toolkit>', 'The toolkit, as `list` prints it, such as googlecalendar.', toolkitSlug)
51
52
  // Required, but checked in the action: commander's own refusal exits 1, not the usage exit 2.
@@ -9,6 +9,7 @@ import { jsonRequested } from '../runtime/runtime.js';
9
9
  import { connectionOf, failureOf, isRow, oneLine, readOverview, rowsOf, TOOLS_PATH, transportFailure, } from '../integrations/api.js';
10
10
  import { FILE_UPLOAD_PATH, fileSize, MAX_FILE_BYTES, md5Of, mimetypeOf, parseFileArgument, putFile, setAt, uploadName, } from '../integrations/file-upload.js';
11
11
  import { choiceLines, renderOverview } from '../integrations/render.js';
12
+ import { withRanOn } from '../integrations/ran-on.js';
12
13
  /**
13
14
  * `kosuke integrations list|call|request` and `kosuke integrations tools get`: the connected tools,
14
15
  * listed and run from a laptop or an agent's shell. Hand-written because the output is text
@@ -124,6 +125,21 @@ function failureText(text, choices, tool, given) {
124
125
  }
125
126
  return body.message;
126
127
  }
128
+ function ranOnLine(connection) {
129
+ const identity = connection.accountIdentity ?? 'account unknown';
130
+ return `Ran on ${connection.alias} (${connection.scope}, "${connection.label}", ${identity}).\n`;
131
+ }
132
+ function isJson(text) {
133
+ if (text.trim() === '')
134
+ return false;
135
+ try {
136
+ JSON.parse(text);
137
+ return true;
138
+ }
139
+ catch {
140
+ return false;
141
+ }
142
+ }
127
143
  /** The reserved upload a successful file-upload answer carries in its text. */
128
144
  function uploadOf(answer) {
129
145
  const block = rowsOf(answer.content)[0];
@@ -153,7 +169,7 @@ function uploadOf(answer) {
153
169
  export function attachIntegrationsCommands(root, runtime, deps = {}) {
154
170
  const { stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), exit = (code) => {
155
171
  process.exitCode = code;
156
- }, readStdin = readAllStdin, stdinHasInput = realStdinHasInput, readFile: readText = (path) => readFile(path, 'utf8'), readTimeoutMs = READ_TIMEOUT_MS, callTimeoutMs = CALL_TIMEOUT_MS, uploadFetch = (input, init) => globalThis.fetch(input, init), env = process.env, } = deps;
172
+ }, readStdin = readAllStdin, stdinHasInput = realStdinHasInput, readFile: readText = (path) => readFile(path, 'utf8'), readTimeoutMs = READ_TIMEOUT_MS, callTimeoutMs = CALL_TIMEOUT_MS, uploadFetch = (input, init) => globalThis.fetch(input, init), env = process.env, stdoutIsTTY = process.stdout.isTTY === true, } = deps;
157
173
  const fail = (failure, code = EXIT_FAILED) => {
158
174
  stderr(`${typeof failure === 'string' ? failure : failure.message}\n`);
159
175
  exit(code);
@@ -197,8 +213,8 @@ export function attachIntegrationsCommands(root, runtime, deps = {}) {
197
213
  // The program's own --json takes the flag wherever it is written, so it is read from there.
198
214
  if (jsonRequested(command.optsWithGlobals().json, env)) {
199
215
  stdout(`${JSON.stringify(result.raw, null, 2)}\n`);
200
- // stdout stays parseable, so the cut is told beside it.
201
- if (result.overview.note)
216
+ // The answer's own `note` says it too; a pipe gets nothing beside the JSON.
217
+ if (result.overview.note && stdoutIsTTY)
202
218
  stderr(`${result.overview.note}\n`);
203
219
  return;
204
220
  }
@@ -250,7 +266,8 @@ export function attachIntegrationsCommands(root, runtime, deps = {}) {
250
266
  }));
251
267
  leafAt(root, HAND_WRITTEN.integrationsCall.command)
252
268
  .description('Run a tool with a JSON object of arguments and print its text result. The connection it ' +
253
- 'ran on is named on stderr. A tool that reports an error exits 1.')
269
+ 'ran on is named on stderr at a terminal; piped, a JSON object result carries it as meta.ranOn. ' +
270
+ 'A tool that reports an error exits 1.')
254
271
  .argument('<name>', 'The tool, as `list` prints it.')
255
272
  .argument('[stdin]', 'A lone - reads the JSON arguments from stdin.')
256
273
  .option('--account <account>', 'The connection to run on: an alias, id or scope:label. Needed when several can run the tool.', accountText)
@@ -414,7 +431,10 @@ export function attachIntegrationsCommands(root, runtime, deps = {}) {
414
431
  throw new UsageError('The arguments must be a JSON object.');
415
432
  return parsed;
416
433
  }
417
- /** The tool's text on stdout; which connection ran it, and any failure, on stderr. */
434
+ /**
435
+ * The tool's text on stdout; any failure on stderr. Which connection ran it goes on stderr at a
436
+ * terminal; when stdout is a pipe, a JSON object answer carries it as `meta.ranOn` instead.
437
+ */
418
438
  function report(name, account, data) {
419
439
  const answer = isRow(data) ? data : {};
420
440
  const content = rowsOf(answer.content);
@@ -426,10 +446,21 @@ export function attachIntegrationsCommands(root, runtime, deps = {}) {
426
446
  .join('\n');
427
447
  const connection = isRow(answer.connection) ? connectionOf(answer.connection) : null;
428
448
  // The alias may name a different connection tomorrow, so every call says which one it ran on.
429
- if (connection) {
430
- const identity = connection.accountIdentity ?? 'account unknown';
431
- stderr(`Ran on ${connection.alias} (${connection.scope}, "${connection.label}", ${identity}).\n`);
449
+ const ranOn = connection ? ranOnLine(connection) : null;
450
+ if (answer.isError !== true && connection && !stdoutIsTTY) {
451
+ const json = withRanOn(text, connection);
452
+ if (json !== null) {
453
+ stdout(`${json}\n`);
454
+ return;
455
+ }
456
+ // Any other JSON keeps stdout one value; plain text is no JSON, so the line stays beside it.
457
+ if (isJson(text)) {
458
+ stdout(text.endsWith('\n') || text === '' ? text : `${text}\n`);
459
+ return;
460
+ }
432
461
  }
462
+ if (ranOn)
463
+ stderr(ranOn);
433
464
  if (answer.isError === true) {
434
465
  const choices = rowsOf(answer.choices).flatMap((row) => connectionOf(row) ?? []);
435
466
  const message = failureText(text, choices, oneLine(name, 80), account);
@@ -0,0 +1,92 @@
1
+ import { isRow } from './api.js';
2
+ /**
3
+ * `meta.ranOn` in a tool's JSON object answer, written into the text itself: a vendor's numbers
4
+ * are never parsed and printed again, so an id past 2^53 keeps every digit.
5
+ */
6
+ /**
7
+ * The tool's JSON object text with `meta.ranOn` naming the connection, or null when the text is
8
+ * no JSON object, its `meta` is no object, or its `meta` already has a `ranOn` of the vendor's.
9
+ */
10
+ export function withRanOn(text, connection) {
11
+ let body;
12
+ try {
13
+ body = JSON.parse(text);
14
+ }
15
+ catch {
16
+ return null;
17
+ }
18
+ if (!isRow(body))
19
+ return null;
20
+ const ranOn = JSON.stringify({
21
+ alias: connection.alias,
22
+ scope: connection.scope,
23
+ label: connection.label,
24
+ account: connection.accountIdentity,
25
+ });
26
+ if (!Object.hasOwn(body, 'meta'))
27
+ return insertBeforeClose(text, text.trimEnd().length - 1, `"meta":{"ranOn":${ranOn}}`);
28
+ if (!isRow(body.meta) || Object.hasOwn(body.meta, 'ranOn'))
29
+ return null;
30
+ const close = metaClose(text);
31
+ return close === null ? null : insertBeforeClose(text, close, `"ranOn":${ranOn}`);
32
+ }
33
+ /** `member` added as the last member of the object whose `}` is at `close`. */
34
+ function insertBeforeClose(text, close, member) {
35
+ const head = text.slice(0, close).trimEnd();
36
+ return `${head}${head.endsWith('{') ? '' : ','}${member}${text.slice(close).trimEnd()}`;
37
+ }
38
+ /**
39
+ * Where the top-level `meta` object closes, read as JSON.parse reads it (the last `meta` wins),
40
+ * or null when it is not found. The text is valid JSON: JSON.parse read it first.
41
+ */
42
+ function metaClose(text) {
43
+ let depth = 0;
44
+ let expectKey = false;
45
+ let metaNext = false;
46
+ let metaDepthOpen = false;
47
+ let found = null;
48
+ for (let at = 0; at < text.length; at++) {
49
+ const char = text[at];
50
+ if (char === '"') {
51
+ const end = stringEnd(text, at);
52
+ if (depth === 1 && expectKey) {
53
+ metaNext = JSON.parse(text.slice(at, end + 1)) === 'meta';
54
+ expectKey = false;
55
+ }
56
+ at = end;
57
+ continue;
58
+ }
59
+ if (char === '{' || char === '[') {
60
+ depth += 1;
61
+ if (depth === 1)
62
+ expectKey = true;
63
+ if (depth === 2 && metaNext && char === '{')
64
+ metaDepthOpen = true;
65
+ metaNext = false;
66
+ continue;
67
+ }
68
+ if (char === '}' || char === ']') {
69
+ if (depth === 2 && metaDepthOpen) {
70
+ found = at;
71
+ metaDepthOpen = false;
72
+ }
73
+ depth -= 1;
74
+ continue;
75
+ }
76
+ if (char === ',' && depth === 1) {
77
+ expectKey = true;
78
+ metaNext = false;
79
+ }
80
+ }
81
+ return found;
82
+ }
83
+ /** The index of the quote that closes the string opened at `start`. */
84
+ function stringEnd(text, start) {
85
+ for (let at = start + 1; at < text.length; at++) {
86
+ if (text[at] === '\\')
87
+ at += 1;
88
+ else if (text[at] === '"')
89
+ return at;
90
+ }
91
+ return text.length - 1;
92
+ }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * The short default of the list commands: at most `DEFAULT_LIST_LIMIT` rows, each cut to the
3
- * fields a reader picks a row by (a null one left out), and a footer on stderr with the total
4
- * and the next page.
3
+ * fields a reader picks a row by (a null one left out), and a footer with the total and the next
4
+ * page: on stderr at a terminal, in the answer's `meta.hint` when stdout is a pipe.
5
5
  * `--all` keeps every row the platform answers, `--full` every field; `--json` (or
6
6
  * `KOSUKE_OUTPUT=json`) prints the platform's whole answer, as before, and sends what it sent.
7
7
  *
@@ -13,6 +13,36 @@ export function createRuntime({ flags, env = process.env, fetch, stdout = (line)
13
13
  }, tty = { stdout: process.stdout.isTTY === true, stderr: process.stderr.isTTY === true }, }) {
14
14
  let resolved = null;
15
15
  const credentials = () => (resolved ??= resolveCredentials(flags, env));
16
+ // Notices held for the answer while stdout is a pipe: an agent that merges stderr into the
17
+ // stream it parses must still read one JSON value.
18
+ const held = [];
19
+ const flushHeld = () => {
20
+ for (const line of held.splice(0))
21
+ stderr(line);
22
+ };
23
+ /** The JSON to print with the footer and held notices in its `meta`, or null when it has none. */
24
+ const withHints = (json, footer) => {
25
+ if (tty.stdout)
26
+ return json;
27
+ const hints = {
28
+ ...(footer ? { hint: footer } : {}),
29
+ ...(held.length ? { notices: held.splice(0) } : {}),
30
+ };
31
+ if (!Object.keys(hints).length)
32
+ return json;
33
+ const placed = metaWith(json, hints);
34
+ // No object to hold them: a footer is left out, so stdout stays one JSON value.
35
+ if (placed === null) {
36
+ for (const line of hints.notices ?? [])
37
+ stderr(line);
38
+ return json;
39
+ }
40
+ return placed;
41
+ };
42
+ const printFooter = (footer) => {
43
+ if (footer)
44
+ stderr(footer);
45
+ };
16
46
  return {
17
47
  credentials,
18
48
  client({ anonymous = false, answerTimeoutMs } = {}) {
@@ -31,7 +61,10 @@ export function createRuntime({ flags, env = process.env, fetch, stdout = (line)
31
61
  });
32
62
  },
33
63
  notice(line) {
34
- stderr(line);
64
+ if (tty.stdout)
65
+ stderr(line);
66
+ else
67
+ held.push(line);
35
68
  },
36
69
  // `--format json` names JSON as `--json` does: the platform's whole answer.
37
70
  wholeAnswer: () => jsonRequested(flags.json, env) || flags.format === 'json',
@@ -40,17 +73,25 @@ export function createRuntime({ flags, env = process.env, fetch, stdout = (line)
40
73
  // 204 has nothing to print; anything else is passed through as JSON so
41
74
  // `| jq` works without the platform CLI knowing the shape.
42
75
  if (outcome.body === undefined)
43
- return;
76
+ return flushHeld();
44
77
  const shaping = flags.fields?.length || flags.format === 'compact';
45
78
  if (!shaping || typeof outcome.body === 'string') {
46
79
  if (shaping) {
80
+ flushHeld();
47
81
  stderr('error: this command printed text, not JSON; --fields and --format need JSON.');
48
82
  exit(1);
49
83
  return;
50
84
  }
51
- stdout(render(outcome.body, flags.pretty || tty.stdout));
52
- if (context?.footer)
53
- stderr(context.footer);
85
+ if (typeof outcome.body === 'string') {
86
+ // Text, not JSON: nothing to parse, so the lines stay beside it.
87
+ flushHeld();
88
+ stdout(outcome.body);
89
+ printFooter(context?.footer);
90
+ return;
91
+ }
92
+ stdout(render(withHints(outcome.body, context?.footer), flags.pretty || tty.stdout));
93
+ if (tty.stdout)
94
+ printFooter(context?.footer);
54
95
  return;
55
96
  }
56
97
  const shaped = shape(outcome.body, {
@@ -59,24 +100,27 @@ export function createRuntime({ flags, env = process.env, fetch, stdout = (line)
59
100
  list: context?.list === true,
60
101
  });
61
102
  if (!shaped.ok) {
103
+ flushHeld();
62
104
  stderr(shaped.message);
63
105
  exit(1);
64
106
  return;
65
107
  }
66
108
  if ('compact' in shaped) {
109
+ // A table, not JSON: what lies beside it stays on stderr.
110
+ flushHeld();
67
111
  if (shaped.compact)
68
112
  stdout(shaped.compact);
69
113
  if (shaped.meta)
70
114
  stderr(shaped.meta);
71
- if (context?.footer)
72
- stderr(context.footer);
115
+ printFooter(context?.footer);
73
116
  return;
74
117
  }
75
- stdout(render(shaped.json, flags.pretty || tty.stdout));
76
- if (context?.footer)
77
- stderr(context.footer);
118
+ stdout(render(withHints(shaped.json, context?.footer), flags.pretty || tty.stdout));
119
+ if (tty.stdout)
120
+ printFooter(context?.footer);
78
121
  return;
79
122
  }
123
+ flushHeld();
80
124
  stderr(render(outcome.body ?? { error: `HTTP ${outcome.status}` }, flags.pretty || tty.stderr));
81
125
  exit(1);
82
126
  },
@@ -102,6 +146,19 @@ function render(body, pretty) {
102
146
  : `${JSON.stringify(key)}:${JSON.stringify(value)}`);
103
147
  return `{${members.join(',')}}`;
104
148
  }
149
+ /**
150
+ * The object with `additions` merged into its `meta`, `meta` keeping its place (last when new);
151
+ * null when the value is no object or its `meta` is no object.
152
+ */
153
+ function metaWith(value, additions) {
154
+ if (!isRecord(value))
155
+ return null;
156
+ if (value.meta === undefined)
157
+ return { ...value, meta: additions };
158
+ if (!isRecord(value.meta))
159
+ return null;
160
+ return { ...value, meta: { ...value.meta, ...additions } };
161
+ }
105
162
  function isRecord(value) {
106
163
  return typeof value === 'object' && value !== null && !Array.isArray(value);
107
164
  }
@@ -1,3 +1,4 @@
1
+ import { editDistance } from './help.js';
1
2
  import { UsageError } from './invoke.js';
2
3
  /** The word that reaches a personal form. */
3
4
  export const PERSONAL = 'personal';
@@ -161,7 +162,7 @@ export function selectForm(forms, { first, flags }, reachable = () => true) {
161
162
  if (leafFlag.forms.has(form) || form.variant?.when?.flag === leafFlag.flag)
162
163
  continue;
163
164
  // A selector of another scope is not a flag of this form either.
164
- throw new UsageError(`--${leafFlag.flag} is not a flag of ${formLabel(form)} of ${command}.`);
165
+ throw new UsageError(misplacedFlag(leafFlag, form, command, shape));
165
166
  }
166
167
  for (const leafFlag of shape.flags) {
167
168
  const field = leafFlag.forms.get(form);
@@ -171,6 +172,36 @@ export function selectForm(forms, { first, flags }, reachable = () => true) {
171
172
  }
172
173
  return form;
173
174
  }
175
+ /**
176
+ * `--x is not a flag of this form`, then the forms that take it and this form's flag closest in
177
+ * spelling, so a script that names the wrong one learns the fix from the error alone.
178
+ */
179
+ function misplacedFlag(leafFlag, form, command, shape) {
180
+ const lines = [`--${leafFlag.flag} is not a flag of ${formLabel(form)} of ${command}.`];
181
+ const elsewhere = [
182
+ ...new Set([...leafFlag.forms.keys()].map((other) => {
183
+ const scope = scopeOf(other);
184
+ if (scope === 'all' && shape.scope)
185
+ return `${command} with no ${shape.scope.name}`;
186
+ return scopedUsage(command, scope, shape);
187
+ })),
188
+ ];
189
+ if (elsewhere.length)
190
+ lines.push(`It is a flag of ${elsewhere.join(' and of ')}.`);
191
+ const near = shape.flags
192
+ .filter((candidate) => candidate !== leafFlag && candidate.forms.has(form))
193
+ .map((candidate) => ({
194
+ flag: candidate.flag,
195
+ distance: editDistance(leafFlag.flag, candidate.flag),
196
+ }))
197
+ .filter(({ flag, distance }) => distance <= Math.max(2, Math.floor(flag.length / 4)))
198
+ .sort((a, b) => a.distance - b.distance)
199
+ .slice(0, 2);
200
+ if (near.length) {
201
+ lines.push(`Did you mean ${near.map(({ flag }) => `--${flag}`).join(' or ')}?`);
202
+ }
203
+ return lines.join(' ');
204
+ }
174
205
  function scopedUsage(command, scope, shape) {
175
206
  if (!shape.scope || scope === 'all')
176
207
  return command;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kosuke-ai/kosuke",
3
- "version": "1.0.132",
3
+ "version": "1.0.133",
4
4
  "description": "Sensei platform CLI. The client customers install to drive app.kosuke.ai from their own machine.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -43,10 +43,10 @@
43
43
  "minimatch": "^11.0.1"
44
44
  },
45
45
  "kosukeRelease": {
46
- "sourceCommit": "d560b4a99cb491fd93e04fe95be606f0b487f9dc",
47
- "sourceIdentity": "729b0798bbcc2a5979c85eb31da934da06247796c98d459418641956f76399d5",
46
+ "sourceCommit": "f9c5e536c8ce17cc4981f141a590fea51f5f928d",
47
+ "sourceIdentity": "825dd549c0d613d40e2efd168443beeab6164d2b05d732656fc7acbb822d4816",
48
48
  "fragments": [
49
- "sensei-thread-routing-r3snvf.json"
49
+ "cli-piped-json-hints-125ftq.json"
50
50
  ]
51
51
  }
52
52
  }