@kosuke-ai/cli 6.8.0 → 6.9.0

package/README.md

@@ -130,8 +130,37 @@ rest leaves room for, so fewer when you belong to many workspaces, and marks
 seen only the events it prints. The rest stay New for
 `kosuke activity list --unseen`. `--workspace <id>` reads that one workspace
 alone, in both the sessions and the events, and the commands it names for the
-rest carry the same flag. `--peek` prints the same events and marks none seen,
-for an agent that reads the digest before every answer.
+rest carry the same flag; with it, or inside an agent's turn, the digest also
+lists the connected integrations, one line each. `--peek` prints the same
+events and marks none seen, for an agent that reads the digest before every
+answer.
+
+## Integrations
+
+`kosuke integrations` lists, describes and runs the tools of the integrations
+connected to a workspace, and to you.
+
+```sh
+kosuke integrations list --workspace <id>                    # a block per toolkit
+kosuke integrations list --workspace <id> --toolkit gmail    # that toolkit's tools
+kosuke integrations describe <tool> --workspace <id>         # one tool's input schema
+kosuke integrations call <tool> --workspace <id> --account notion-personal --args '{"query":"roadmap"}'
+```
+
+`list` with no filter prints each toolkit's connections (alias, scope, label,
+account, short id) and how many read-only and write tools it has. `--toolkit` and
+`--search` list the matching tools, and a list that is cut short says "N of M"
+and how to narrow it. `--account` takes a connection's alias such as
+`notion-personal`, its short id or `scope:label`; case, curly quotes and extra
+spaces do not matter, and it is needed when several connections can run a tool.
+`call` prints the tool's text on stdout and the connection it ran on on stderr,
+and exits 1 when the tool reports an error.
+
+With an API key, `--workspace` is required (you must belong to it), and `call`
+runs only your own personal connections. Inside an agent's turn the credential
+decides the workspace and the flag is optional. A Connector Token is refused.
+`kosuke integrations tools` and `execute` print the raw JSON of the same two
+routes. `kosuke agent summary` lists the same connections, one line each.
 
 ## Generated from the API
 

package/dist/agent/summary.js

@@ -1,8 +1,10 @@
+import { readOverview } from '../integrations/api.js';
 import { createApiClient } from '../runtime/client.js';
+import { isTurnToken } from '../runtime/credentials.js';
 import { HttpError, NEEDS_YOU_FILTER, paginationTotal } from './http.js';
 /**
- * `kosuke agent summary`: what needs the member, which providers are connected
- * and what is New, in a few dozen lines an agent reads at the start of a
+ * `kosuke agent summary`: what needs the member, which providers and integrations
+ * are connected and what is New, in a few dozen lines an agent reads at the start of a
  * conversation. Kept to about 1,500 tokens: each list is capped and names the
  * command that reads the rest, and it claims only as many events as the other
  * lines leave room for.
@@ -13,7 +15,14 @@ const SUMMARY_TIMEOUT_MS = 8000;
  * must cost the digest its numbers, never the digest.
  */
 const PROVIDERS_TIMEOUT_MS = 4000;
+/**
+ * Shorter still than the providers': connections are one cheap read, and a slow
+ * platform must cost the digest this section, never the digest.
+ */
+const INTEGRATIONS_TIMEOUT_MS = 3000;
 const NEEDS_YOU_SHOWN = 5;
+/** Connections listed before "and N more"; a member's own seven fit. */
+const INTEGRATIONS_SHOWN = 8;
 /** However much room is left: past this, the digest stops being a glance. */
 const EVENTS_SHOWN = 15;
 /**
@@ -222,6 +231,55 @@ async function fetchProviders(client, workspace, signal) {
         return null;
     }
 }
+/**
+ * The Integrations section's lines, one per connection: toolkit, alias, scope, label and the
+ * account it reaches. The platform decides which are the caller's (a member's personal ones come
+ * only where the credential may use them), so this lists what it was sent, each once. Null when
+ * there is no workspace to ask about; a refusal or a failed read still says so, because an
+ * absent section would read as "nothing is connected".
+ */
+async function fetchIntegrations(client, workspace, apiKey, signal) {
+    // A member's key names a workspace; a turn's token already is one.
+    if (!workspace && !isTurnToken(apiKey))
+        return null;
+    try {
+        const result = await readOverview(client, workspace ? { workspace } : {}, signal);
+        if (!result.ok) {
+            return [
+                result.status === 403
+                    ? '- Not available to this credential.'
+                    : '- Could not be read. `kosuke integrations list` retries.',
+            ];
+        }
+        const seen = new Set();
+        const lines = [];
+        for (const toolkit of result.overview.toolkits) {
+            for (const connection of toolkit.connections) {
+                if (seen.has(connection.id))
+                    continue;
+                seen.add(connection.id);
+                lines.push(integrationLine(toolkit.toolkit, connection));
+            }
+        }
+        if (lines.length === 0)
+            return ['- None connected.'];
+        const total = Math.max(result.overview.connectionTotal, lines.length);
+        const shown = lines.slice(0, INTEGRATIONS_SHOWN);
+        if (total > shown.length) {
+            const scope = workspace ? ` --workspace ${workspace}` : '';
+            shown.push(`(and ${total - shown.length} more: kosuke integrations list${scope})`);
+        }
+        return shown;
+    }
+    catch {
+        return null;
+    }
+}
+function integrationLine(toolkit, connection) {
+    const label = clip(connection.label, NAME_MAX);
+    const identity = clip(connection.accountIdentity ?? 'account unknown', NAME_MAX);
+    return `- ${clip(toolkit, NAME_MAX)}: ${connection.alias}, ${connection.scope}, "${label}", ${identity}`;
+}
 /** Never clipped: a workspace missing here would read as one the digest did not cover. */
 function coverageLine(sessions) {
     const covered = sessions?.meta?.workspaces;
@@ -251,6 +309,9 @@ export function planSummary(options) {
     head.push('');
     if (options.providers?.length)
         head.push('Providers:', ...options.providers, '');
+    if (options.integrations?.length) {
+        head.push('Integrations (`kosuke integrations list` shows their tools):', ...options.integrations, '');
+    }
     const coverage = coverageLine(sessions);
     const room = BUDGET_CHARS - head.join('\n').length - coverage.length - ACTIVITY_FRAME_CHARS - scope.length;
     const lineMax = eventLineMax(apiUrl, needing);
@@ -294,7 +355,7 @@ export function renderSummary(plan, activity) {
 }
 /**
  * The whole digest, or one line saying why not, so the agent reading it
- * knows to query the CLI itself. Needs You and the providers are read first:
+ * knows to query the CLI itself. Needs You, the providers and the integrations are read first:
  * their lines decide how many events fit, and the Activity read marks events
  * seen, so a digest that failed after it would lose them.
  */
@@ -309,17 +370,19 @@ export async function fetchSummary(options) {
     const signal = AbortSignal.timeout(options.timeoutMs ?? SUMMARY_TIMEOUT_MS);
     try {
         const workspace = options.workspace ? { workspace: options.workspace } : {};
-        const [needsYou, providers] = await Promise.all([
+        const [needsYou, providers, integrations] = await Promise.all([
             client.GET('/api/chat-sessions', {
                 params: { query: { ...NEEDS_YOU_QUERY, ...workspace } },
                 signal,
             }),
             fetchProviders(client, options.workspace, AbortSignal.any([signal, AbortSignal.timeout(PROVIDERS_TIMEOUT_MS)])),
+            fetchIntegrations(client, options.workspace, options.apiKey, AbortSignal.any([signal, AbortSignal.timeout(INTEGRATIONS_TIMEOUT_MS)])),
         ]);
         const sessions = body(needsYou);
         const plan = planSummary({
             sessions,
             providers,
+            integrations,
             apiUrl: options.apiUrl,
             now: (options.now ?? Date.now)(),
             ...workspace,

package/dist/commands/integrations.js

@@ -0,0 +1,303 @@
+import { readFile } from 'node:fs/promises';
+import { InvalidArgumentError } from 'commander';
+import { groupFor } from '../runtime/attach.js';
+import { isTurnToken } from '../runtime/credentials.js';
+import { connectionOf, failureOf, isRow, oneLine, readOverview, rowsOf, TOOLS_PATH, transportFailure, } from '../integrations/api.js';
+import { choiceLines, renderOverview } from '../integrations/render.js';
+/**
+ * `kosuke integrations list|describe|call`: the connected tools, listed and run
+ * from a laptop or an agent's shell. Hand-written because the output is text
+ * and the exit code says whether the tool worked, which the generated
+ * `integrations tools` and `integrations execute` (raw JSON passthroughs, kept
+ * beside these) cannot do.
+ *
+ * Tool descriptions, schemas and results come from third-party services: they
+ * are printed, never acted on.
+ */
+const EXECUTE_PATH = '/api/agent-integrations/execute';
+const READ_TIMEOUT_MS = 30_000;
+/** A guarded call is up to three sequential vendor requests of 20 s each. */
+const CALL_TIMEOUT_MS = 70_000;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+const TOOLKIT_PATTERN = /^[a-z0-9_]{1,64}$/;
+const MAX_SEARCH_CHARS = 100;
+const MAX_ACCOUNT_CHARS = 100;
+/** Wrong flags or arguments, found before any request. */
+class UsageError extends Error {
+}
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function toolkitSlug(raw) {
+    if (!TOOLKIT_PATTERN.test(raw)) {
+        throw new InvalidArgumentError('Expected a toolkit slug such as gmail, as `list` prints it.');
+    }
+    return raw;
+}
+function searchText(raw) {
+    if (raw.trim() === '' || raw.length > MAX_SEARCH_CHARS) {
+        throw new InvalidArgumentError(`Expected 1 to ${MAX_SEARCH_CHARS} characters.`);
+    }
+    return raw;
+}
+function accountText(raw) {
+    // A flag swallowed as the value (`--account --args`) shows as a leading dash.
+    if (raw.trim() === '' || raw.startsWith('-') || raw.length > MAX_ACCOUNT_CHARS) {
+        throw new InvalidArgumentError(`Expected an alias, a connection id or scope:label, up to ${MAX_ACCOUNT_CHARS} characters.`);
+    }
+    return raw;
+}
+function limitNumber(raw) {
+    if (!/^\d+$/.test(raw) || Number(raw) < 1 || Number(raw) > 100) {
+        throw new InvalidArgumentError('Expected a whole number from 1 to 100.');
+    }
+    return Number(raw);
+}
+const WORKSPACE_HELP = 'The workspace to use. Required with an API key, which is refused when you are not a member of it. ' +
+    'Inside an agent turn the credential decides, and this is optional.';
+/** A turn's token decides its workspace; a member's API key has to name one. */
+function workspaceFor(runtime, given) {
+    if (given)
+        return given;
+    if (isTurnToken(runtime.credentials().apiKey))
+        return undefined;
+    throw new UsageError('--workspace <id> is required with an API key. `kosuke workspaces list` shows the ids.');
+}
+/** The 409 that asks for `--account`: its choices, one per line. */
+function accountChoiceText(error, tool, given) {
+    if (!isRow(error))
+        return null;
+    const choices = rowsOf(isRow(error.details) ? error.details.choices : []).flatMap((row) => connectionOf(row) ?? []);
+    if (choices.length === 0)
+        return null;
+    return choicesSentence(error.code === 'INTEGRATION_INVALID_ACCOUNT', tool, given, choices);
+}
+function choicesSentence(invalid, tool, given, choices) {
+    const head = invalid
+        ? `No single account matches --account "${oneLine(given ?? '', 60)}". The accounts are:`
+        : `More than one account can run ${tool}. Pass --account with one of:`;
+    return `${head}\n${choiceLines(choices)}`;
+}
+/**
+ * The executor answers a tool failure as text. Its own refusals are
+ * `{"error": code, "message": sentence}`, shown as the sentence; anything else
+ * (a vendor's words included) is printed as received.
+ */
+function failureText(text, choices, tool, given) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+    if (!isRow(body) || typeof body.message !== 'string' || typeof body.error !== 'string') {
+        return text;
+    }
+    if (body.error === 'account_required' || body.error === 'invalid_account') {
+        return choices.length > 0
+            ? choicesSentence(body.error === 'invalid_account', tool, given, choices)
+            : body.message.replace(/\bPass account\b/, 'Pass --account');
+    }
+    return body.message;
+}
+export function attachIntegrationsCommands(root, runtime, deps = {}) {
+    const { stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), exit = (code) => {
+        process.exitCode = code;
+    }, readStdin = readAllStdin, readFile: readText = (path) => readFile(path, 'utf8'), readTimeoutMs = READ_TIMEOUT_MS, callTimeoutMs = CALL_TIMEOUT_MS, } = deps;
+    const fail = (failure, code = EXIT_FAILED) => {
+        stderr(`${typeof failure === 'string' ? failure : failure.message}\n`);
+        exit(code);
+    };
+    /** Runs one command; a usage error is reported and exits 2. */
+    const guarded = (run) => async (...args) => {
+        try {
+            await run(...args);
+        }
+        catch (error) {
+            if (!(error instanceof UsageError))
+                throw error;
+            fail(error.message, EXIT_USAGE);
+        }
+    };
+    const group = groupFor(root, ['integrations']);
+    group
+        .command('list')
+        .description('List the connected tools. With no filter, one block per toolkit: its connections (alias, ' +
+        'scope, label, account, id) and how many read-only and write tools it has. --toolkit and ' +
+        '--search list the matching tools. A cut list says "N of M" and how to narrow it.')
+        .option('--toolkit <slug>', 'Only this toolkit, such as gmail.', toolkitSlug)
+        .option('--search <text>', 'Only tools whose name or description mention the text.', searchText)
+        .option('--account <account>', 'Only what one connection offers: an alias, id or scope:label.', accountText)
+        .option('--limit <n>', 'How many tools to list with --toolkit or --search. Default 40, at most 100.', limitNumber)
+        .option('--workspace <id>', WORKSPACE_HELP)
+        .option('--json', "Print the platform's answer as JSON.")
+        .addHelpText('after', '\nExit codes:\n  0  ok\n  1  the platform refused or could not answer\n  2  --workspace missing with an API key')
+        .action(guarded(async (flags) => {
+        const client = runtime.client();
+        const workspace = workspaceFor(runtime, flags.workspace);
+        const result = await readOverview(client, {
+            ...(workspace ? { workspace } : {}),
+            ...(flags.toolkit ? { toolkit: flags.toolkit } : {}),
+            ...(flags.search ? { search: flags.search } : {}),
+            ...(flags.account ? { account: flags.account } : {}),
+            ...(flags.limit ? { limit: flags.limit } : {}),
+        }, AbortSignal.timeout(readTimeoutMs));
+        if (!result.ok)
+            return fail(result);
+        if (flags.json) {
+            stdout(`${JSON.stringify(result.raw, null, 2)}\n`);
+            // stdout stays parseable, so the cut is told beside it.
+            if (result.overview.note)
+                stderr(`${result.overview.note}\n`);
+            return;
+        }
+        stdout(renderOverview(result.overview, Boolean(flags.toolkit || flags.search)));
+    }));
+    group
+        .command('describe')
+        .description("Print one tool's input schema and annotations as JSON.")
+        .argument('<name>', 'The tool, as `list` prints it.')
+        .option('--account <account>', 'The connection whose schema you want: an alias, id or scope:label. Needed when several can run the tool.', accountText)
+        .option('--workspace <id>', WORKSPACE_HELP)
+        .addHelpText('after', '\nExit codes:\n  0  ok\n  1  no such tool, a connection has to be named, or the platform refused\n  2  --workspace missing with an API key')
+        .action(guarded(async (name, flags) => {
+        const client = runtime.client();
+        const workspace = workspaceFor(runtime, flags.workspace);
+        try {
+            const { data, error, response } = await client.GET(TOOLS_PATH, {
+                params: {
+                    query: {
+                        name,
+                        ...(flags.account ? { account: flags.account } : {}),
+                        ...(workspace ? { workspace } : {}),
+                    },
+                },
+                signal: AbortSignal.timeout(readTimeoutMs),
+            });
+            if (response.status === 404) {
+                return fail(`No connected tool is named ${oneLine(name, 80)}${flags.account ? ' for that account' : ''}. ` +
+                    'Run `kosuke integrations list` to see them.');
+            }
+            if (response.status === 409) {
+                const choices = accountChoiceText(error, oneLine(name, 80), flags.account);
+                if (choices)
+                    return fail(choices);
+            }
+            if (!response.ok)
+                return fail(failureOf(response.status, error, 'GET'));
+            const tools = rowsOf(isRow(data) && isRow(data.data) ? data.data.tools : []);
+            // Matched here too: a platform that ignores `name` answers with every tool.
+            const tool = tools.find((entry) => typeof entry.name === 'string' && entry.name.toLowerCase() === name.toLowerCase());
+            if (!tool) {
+                return fail(`No connected tool is named ${oneLine(name, 80)}. Run \`kosuke integrations list\` to see them.`);
+            }
+            const { description, inputSchema, annotations } = tool;
+            stdout(`${JSON.stringify({ name: tool.name, description, inputSchema, annotations }, null, 2)}\n`);
+        }
+        catch (error) {
+            fail(transportFailure(error, 'GET'));
+        }
+    }));
+    group
+        .command('call')
+        .description('Run a tool with a JSON object of arguments and print its text result. The connection it ' +
+        'ran on is named on stderr. A tool that reports an error exits 1.')
+        .argument('<name>', 'The tool, as `list` prints it.')
+        .argument('[stdin]', 'A lone - reads the JSON arguments from stdin.')
+        .option('--account <account>', 'The connection to run on: an alias, id or scope:label. Needed when several can run the tool.', accountText)
+        .option('--args <json>', 'The tool arguments, a JSON object. Default {}.')
+        .option('--args-file <path>', 'Read the arguments from a file, or - for stdin.')
+        .option('--workspace <id>', WORKSPACE_HELP)
+        .addHelpText('after', '\nWith an API key, a call runs only on your own personal connections; one on a workspace\n' +
+        "connection is refused (an agent's turn in the workspace can run it).\n" +
+        '\nExit codes:\n  0  the tool ran\n  1  the tool or the platform reported an error, or the outcome of a write is unknown\n  2  usage error: --workspace missing, or arguments that are not a JSON object')
+        .action(guarded(async (name, dash, flags) => {
+        const toolArguments = await readArguments(flags, dash);
+        const client = runtime.client();
+        const workspace = workspaceFor(runtime, flags.workspace);
+        let data;
+        try {
+            const result = await client.POST(EXECUTE_PATH, {
+                params: { query: workspace ? { workspace } : {} },
+                body: {
+                    name,
+                    arguments: toolArguments,
+                    ...(flags.account ? { account: flags.account } : {}),
+                },
+                signal: AbortSignal.timeout(callTimeoutMs),
+            });
+            if (!result.response.ok) {
+                return fail(failureOf(result.response.status, result.error, 'POST'));
+            }
+            data = isRow(result.data) ? result.data.data : undefined;
+        }
+        catch (error) {
+            return fail(transportFailure(error, 'POST'));
+        }
+        report(name, flags.account, data);
+    }));
+    /** Reads `--args`, `--args-file` or a lone `-`: one source at most, and a JSON object. */
+    async function readArguments(flags, dash) {
+        if (dash !== undefined && dash !== '-')
+            throw new UsageError(`Unexpected argument: ${dash}`);
+        const fromStdin = dash === '-' || flags.argsFile === '-';
+        // Each flag and the positional `-` is its own source, even when two of them name stdin.
+        const sources = [flags.args !== undefined, flags.argsFile !== undefined, dash === '-'];
+        if (sources.filter(Boolean).length > 1)
+            throw new UsageError('Give the arguments one way only.');
+        if (!sources.includes(true))
+            return {};
+        let text;
+        if (flags.args !== undefined)
+            text = flags.args;
+        else if (fromStdin)
+            text = await readStdin();
+        else {
+            try {
+                text = await readText(flags.argsFile);
+            }
+            catch {
+                throw new UsageError(`Could not read the arguments file ${flags.argsFile}.`);
+            }
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new UsageError('The arguments are not valid JSON.');
+        }
+        if (!isRow(parsed))
+            throw new UsageError('The arguments must be a JSON object.');
+        return parsed;
+    }
+    /** The tool's text on stdout; which connection ran it, and any failure, on stderr. */
+    function report(name, account, data) {
+        const answer = isRow(data) ? data : {};
+        const content = rowsOf(answer.content);
+        if (content.length === 0 && !Array.isArray(answer.content)) {
+            return fail('Integration tools returned an unexpected response.');
+        }
+        const text = content
+            .map((block) => (typeof block.text === 'string' ? block.text : ''))
+            .join('\n');
+        const connection = isRow(answer.connection) ? connectionOf(answer.connection) : null;
+        // The alias may name a different connection tomorrow, so every call says which one it ran on.
+        if (connection) {
+            const identity = connection.accountIdentity ?? 'account unknown';
+            stderr(`Ran on ${connection.alias} (${connection.scope}, "${connection.label}", ${identity}).\n`);
+        }
+        if (answer.isError === true) {
+            const choices = rowsOf(answer.choices).flatMap((row) => connectionOf(row) ?? []);
+            const message = failureText(text, choices, oneLine(name, 80), account);
+            fail(message.endsWith('\n') ? message.slice(0, -1) : message);
+            return;
+        }
+        stdout(text.endsWith('\n') || text === '' ? text : `${text}\n`);
+    }
+}