@kosuke-ai/kosuke 1.0.0 → 1.0.2

package/dist/commands/integrations.js

@@ -0,0 +1,310 @@
+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;
+/**
+ * One value for every call: the execute route's `maxDuration`, the longest the platform lets
+ * one run. The platform decides from the tool and the account where a call runs, so the CLI cannot
+ * give the others a shorter wait. They end sooner on the platform's side, a Composio read at its
+ * 60 s budget, and wait no longer than their answer takes.
+ */
+const CALL_TIMEOUT_MS = 330_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" +
+        `\nA call waits up to ${CALL_TIMEOUT_MS / 1000} s for its answer, as long as the platform lets one run.\n` +
+        'A call that gets no answer is never sent again: its outcome is unknown.\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({ answerTimeoutMs: callTimeoutMs });
+        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`);
+    }
+}

package/dist/commands/skill-runs.js

@@ -0,0 +1,230 @@
+import { randomUUID } from 'node:crypto';
+import { appendFile, lstat, readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { agentTokenOf } from '../runtime/agent-tokens.js';
+const FLAGS = new Set([
+    '--fix',
+    '--sync',
+    '--no-review',
+    '--restart',
+    '--ready',
+    '-d',
+    '--draft',
+    '--target-branch',
+    '-r',
+    '--reviewers',
+    '-e',
+    '--evidence',
+]);
+const RESULTS = new Set([
+    'passed',
+    'failed',
+    'blocked',
+    'skipped',
+    'prototype',
+    'question',
+    'ready',
+    'cancelled',
+    'open_items',
+]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEADLINE_MS = 1500;
+async function appendMarker(path, value) {
+    try {
+        const stat = await lstat(path).catch(() => null);
+        if (stat && (!stat.isFile() || stat.size > 512 * 1024))
+            return;
+        await appendFile(path, JSON.stringify(value) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // A bridge failure must not stop the server from recording the marker.
+    }
+}
+async function identity(env) {
+    const projectId = env.KOSUKE_PROJECT_ID;
+    const sessionId = env.KOSUKE_SESSION_ID ?? env.KOSUKE_SANDBOX_KEY;
+    if (projectId && sessionId && UUID.test(projectId) && UUID.test(sessionId))
+        return { projectId, sessionId };
+    try {
+        const session = JSON.parse(await readFile('/tmp/kosuke-session.json', 'utf8'));
+        return typeof session.projectId === 'string' &&
+            UUID.test(session.projectId) &&
+            typeof session.sandboxKey === 'string' &&
+            UUID.test(session.sandboxKey)
+            ? { projectId: session.projectId, sessionId: session.sandboxKey }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function receiptData(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return null;
+    let size = 0;
+    const chunks = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 8192)
+                return null;
+            chunks.push(value);
+        }
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!parsed || typeof parsed !== 'object' || !('data' in parsed))
+            return null;
+        const data = parsed.data;
+        return data !== null && typeof data === 'object' ? data : null;
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+/** Marker errors bypass Commander and the shared retrying client so they cannot stop agent work. */
+export async function runSkillMarkerCommand(args, options = {}) {
+    if (args[0] !== 'sessions' || args[1] !== 'skill-runs')
+        return false;
+    const { env = process.env, fetch: request = globalThis.fetch, stdout = (text) => process.stdout.write(text), timeoutMs = DEADLINE_MS, } = options;
+    if (args.length === 3 && args[2] === '--capabilities') {
+        stdout('skill-markers-v1\n');
+        return true;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        stdout('kosuke sessions skill-runs start <name> [--fix] [--sync] [--no-review]\nkosuke sessions skill-runs end <name> [--result <verdict>]\nBest effort: one request, 1.5-second deadline, always exits 0.\n');
+        return true;
+    }
+    const [, , action, rawName, ...rest] = args;
+    if ((action !== 'start' && action !== 'end') ||
+        !rawName ||
+        !/^(?:kosuke:)?[a-z][a-z0-9-]{0,79}$/.test(rawName))
+        return true;
+    const flags = [];
+    let result;
+    for (let index = 0; index < rest.length; index++) {
+        const value = rest[index];
+        if (value === '--result' && action === 'end' && result === undefined) {
+            result = rest[++index];
+            if (!result || !RESULTS.has(result))
+                return true;
+        }
+        else if (FLAGS.has(value)) {
+            if (!flags.includes(value))
+                flags.push(value);
+        }
+        else
+            return true;
+    }
+    const bridge = env.KOSUKE_SKILL_MARKER_FILE;
+    const clockId = env.KOSUKE_SKILL_CLOCK_ID;
+    if (!bridge ||
+        !isAbsolute(bridge) ||
+        !clockId ||
+        !UUID.test(clockId) ||
+        agentTokenOf(env.KOSUKE_API_KEY) !== 'sandboxToken' ||
+        !env.KOSUKE_API_URL)
+        return true;
+    const controller = new AbortController();
+    const budget = Math.max(1, Math.min(timeoutMs, DEADLINE_MS));
+    const requestTimer = setTimeout(() => controller.abort(), Math.max(1, budget - Math.min(100, budget / 2)));
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve();
+        }, budget);
+    });
+    const operation = async () => {
+        const ids = await identity(env);
+        if (!ids || controller.signal.aborted)
+            return;
+        const marker = {
+            markerId: randomUUID(),
+            action,
+            name: rawName.startsWith('kosuke:') ? rawName : `kosuke:${rawName}`,
+            at: new Date().toISOString(),
+            monotonicMs: Number(process.hrtime.bigint()) / 1e6,
+            clockId,
+            ...(flags.length ? { flags } : {}),
+            ...(result ? { result } : {}),
+        };
+        await appendMarker(bridge, { kind: 'marker', ...marker });
+        if (controller.signal.aborted)
+            return;
+        let status = 'unknown';
+        let accepted = null;
+        try {
+            const response = await request(`${env.KOSUKE_API_URL.replace(/\/+$/, '')}/api/projects/${ids.projectId}/chat-sessions/${ids.sessionId}/skill-runs`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${env.KOSUKE_API_KEY}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(marker),
+                signal: controller.signal,
+                redirect: 'error',
+            });
+            if (response.ok) {
+                accepted = await receiptData(response);
+                if (accepted?.accepted === true && accepted.markerId === marker.markerId)
+                    status = 'accepted';
+            }
+            else {
+                status = 'rejected';
+                await response.body?.cancel();
+            }
+        }
+        catch {
+            /* A lost response does not prove the server rejected the marker. */
+        }
+        await appendMarker(bridge, {
+            kind: 'receipt',
+            markerId: marker.markerId,
+            status,
+            ...(status === 'accepted' &&
+                (accepted?.invocationId === null ||
+                    (typeof accepted?.invocationId === 'string' && UUID.test(accepted.invocationId)))
+                ? { invocationId: accepted.invocationId }
+                : {}),
+            ...(status === 'accepted' && typeof accepted?.noop === 'boolean'
+                ? { noop: accepted.noop }
+                : {}),
+        });
+    };
+    try {
+        await Promise.race([operation().catch(() => undefined), deadline]);
+    }
+    finally {
+        clearTimeout(requestTimer);
+        if (timer)
+            clearTimeout(timer);
+    }
+    return true;
+}
+export function attachSkillMarkerCommands(program, options = {}) {
+    const sessions = program.commands.find((command) => command.name() === 'sessions') ??
+        program.command('sessions');
+    const skills = sessions.commands.find((command) => command.name() === 'skill-runs') ??
+        sessions.command('skill-runs');
+    skills
+        .description('Record best-effort Factory Skill start and end markers.')
+        .option('--capabilities', 'Print marker command capability.')
+        .action(async () => {
+        await runSkillMarkerCommand(['sessions', 'skill-runs', '--capabilities'], options);
+    });
+    for (const action of ['start', 'end']) {
+        const command = skills
+            .command(`${action} <name>`)
+            .description(`${action === 'start' ? 'Start' : 'End'} a Factory Skill in this sandbox Turn.`);
+        for (const flag of FLAGS)
+            command.option(flag);
+        if (action === 'end')
+            command.option('--result <verdict>', 'A known result, such as passed, failed, blocked, or ready.');
+        command.action(async (_name, _flags, cmd) => {
+            await runSkillMarkerCommand(cmd.parent.parent.parent.args, options);
+        });
+    }
+}