@kosuke-ai/kosuke 1.0.0 → 1.0.1

package/dist/runtime/attach.js

@@ -0,0 +1,199 @@
+import { Argument, Command, InvalidArgumentError, Option } from 'commander';
+import { buildRequest, execute, readWholeBody, UsageError } from './invoke.js';
+/**
+ * One commander command per operation descriptor: positionals for path
+ * params, a flag per top-level field, `--body`/`--body-file` for a whole
+ * body and `--attach` where the operation takes files. The command's help is
+ * the contract's summary, verbatim.
+ */
+export function attachOperation(root, operation, runtime) {
+    const leaf = attachLeaf(root, operation.command, operation, runtime, { hidden: false });
+    const name = operation.command.join(' ');
+    for (const [alias, target] of COMMAND_ALIASES) {
+        if (target === name) {
+            attachLeaf(root, alias.split(' '), operation, runtime, {
+                hidden: true,
+                workspaceArgument: true,
+            });
+        }
+    }
+    return leaf;
+}
+// Alias: Sensei's commands from when it was a workspace's, `kosuke workspaces sensei-* <id>`,
+// and the Lead's names for them, which an older sandbox's Sensei prompt still runs; remove the
+// Lead's one release after the Sensei rename, Sensei's one release after Sensei moved to the
+// person. The workspace they take goes to `--workspace` where the command reads one.
+const COMMAND_ALIASES = new Map([
+    ['cards', 'sensei cards'],
+    ['merge', 'sensei merge'],
+    ['notifications open', 'sensei notifications open'],
+].flatMap(([old, target]) => [
+    [`workspaces sensei-${old}`, target],
+    [`workspaces lead-${old}`, target],
+]));
+function attachLeaf(root, path, operation, runtime, { hidden, workspaceArgument = false }) {
+    const parent = groupFor(root, path.slice(0, -1), { hidden });
+    const leaf = parent.command(path[path.length - 1], { hidden });
+    leaf.description(operation.summary);
+    if (workspaceArgument)
+        leaf.addArgument(new Argument('<workspaceId>', 'Workspace id'));
+    for (const name of operation.pathParams) {
+        leaf.addArgument(new Argument(`<${name}>`, humanize(name)));
+    }
+    const fields = dedupe([
+        ...operation.query,
+        ...(operation.body?.fields ?? []),
+        ...(operation.multipart ?? []),
+    ]);
+    for (const field of fields) {
+        leaf.addOption(optionFor(field));
+        // Both spellings, so a field whose meaningful value is false (members
+        // --no-include-invitations) can be said; neither given leaves it unsent.
+        if (field.kind === 'boolean') {
+            leaf.addOption(new Option(`--no-${field.flag}`, `Send ${field.name} as false.`));
+        }
+    }
+    const takesBody = operation.body !== null || operation.multipart !== null;
+    if (takesBody) {
+        leaf.option('--body <json>', 'The whole request body as JSON; overrides field flags.');
+        leaf.option('--body-file <path>', 'Read the whole request body from a file, or - for stdin.');
+    }
+    if (operation.attachments) {
+        leaf.option('--attach <path>', 'Attach a file; repeat for several. Sends the request as multipart.', collect, []);
+    }
+    leaf.action(async (...args) => {
+        const options = args[args.length - 2];
+        const offset = workspaceArgument ? 1 : 0;
+        const positionals = args.slice(offset, offset + operation.pathParams.length);
+        const workspace = workspaceArgument ? args[0] : undefined;
+        const input = {
+            pathParams: Object.fromEntries(operation.pathParams.map((name, i) => [name, positionals[i]])),
+            fields: Object.fromEntries(fields.map((field) => {
+                const given = options[optionKey(field.flag)];
+                // The old command's workspace filters a read that takes one; a write names its own.
+                const value = given ?? (field.name === 'workspace' ? workspace : undefined);
+                return [field.name, value];
+            })),
+            wholeBody: readWholeBody({
+                body: options.body,
+                bodyFile: options.bodyFile,
+            }),
+            attachments: options.attach ?? [],
+        };
+        let request;
+        try {
+            request = buildRequest(operation, input);
+        }
+        catch (error) {
+            if (error instanceof UsageError)
+                leaf.error(error.message);
+            throw error;
+        }
+        const client = runtime.client({
+            anonymous: operation.anonymous,
+            answerTimeoutMs: operation.answerTimeoutMs,
+        });
+        const outcome = await execute(client, request);
+        runtime.output(outcome);
+    });
+    return leaf;
+}
+/** A group created here is hidden when asked; one that already exists keeps what it is. */
+export function groupFor(root, path, { hidden = false } = {}) {
+    let current = root;
+    for (const segment of path) {
+        const existing = current.commands.find((command) => command.name() === segment);
+        current =
+            existing ?? current.command(segment, { hidden }).description(`${humanize(segment)} commands`);
+    }
+    return current;
+}
+function optionFor(field) {
+    const description = field.description ?? '';
+    if (field.repeated)
+        return repeatedOption(field, description);
+    if (field.kind === 'boolean')
+        return new Option(`--${field.flag}`, description);
+    const option = new Option(`--${field.flag} <value>`, description);
+    if (field.choices)
+        option.choices([...field.choices]);
+    if (field.kind === 'number' || field.kind === 'integer')
+        option.argParser(numberParser(field));
+    if (field.kind === 'json')
+        option.argParser(jsonParser);
+    return option;
+}
+/**
+ * One value per flag, collected into the array the wire takes. `choices` is
+ * set for the help text and then overridden, because its own parser keeps
+ * only the last value of a flag that is not variadic.
+ */
+function repeatedOption(field, description) {
+    const option = new Option(`--${field.flag} <value>`, `${description} Repeat for several.`.trim());
+    if (field.choices)
+        option.choices([...field.choices]);
+    const parse = field.kind === 'number' || field.kind === 'integer'
+        ? numberParser(field)
+        : (raw) => raw;
+    return option.argParser((raw, previous) => {
+        if (field.choices && !field.choices.includes(raw)) {
+            throw new InvalidArgumentError(`Allowed choices are ${field.choices.join(', ')}.`);
+        }
+        return [...(previous ?? []), field.kind === 'boolean' ? raw === 'true' : parse(raw)];
+    });
+}
+/**
+ * Decimal digits only. `Number()` reads '' as 0, '0x10' as 16 and '1e999' as
+ * Infinity (which JSON writes as null), none of which a customer meant.
+ */
+const DECIMAL = /^-?\d+(\.\d+)?$/;
+const INTEGER = /^-?\d+$/;
+function numberParser(field) {
+    return (raw) => {
+        const pattern = field.kind === 'integer' ? INTEGER : DECIMAL;
+        if (!pattern.test(raw)) {
+            throw new InvalidArgumentError(field.kind === 'integer' ? 'Expected an integer.' : 'Expected a number.');
+        }
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new InvalidArgumentError('Expected a finite number.');
+        return value;
+    };
+}
+function jsonParser(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new InvalidArgumentError('Expected JSON.');
+    }
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+/**
+ * One option per flag. The generator gives the same wire name on the JSON and
+ * the form branch one flag, and two wire names never one flag; this keys on
+ * the flag because that is what commander refuses to register twice.
+ */
+function dedupe(fields) {
+    const seen = new Set();
+    return fields.filter((field) => {
+        if (seen.has(field.flag))
+            return false;
+        seen.add(field.flag);
+        return true;
+    });
+}
+/** commander stores `--exclude-archived` as `excludeArchived`. */
+export function optionKey(flag) {
+    return flag.replace(/-([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+/** `projectId` reads as `Project id`; `env-vars` as `Env vars`. */
+export function humanize(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/-/g, ' ')
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}

package/dist/runtime/attachments.js

@@ -0,0 +1,63 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+/**
+ * Files on a multipart request, the way the platform reads them.
+ *
+ * Hand-written on purpose. The API takes `attachmentCount` and one file per
+ * `attachment_<i>` field, and a field whose name carries an index is not
+ * something an OpenAPI document can describe: the spec marks the operation
+ * with `x-kosuke-attachments` and its limits and stops there, so the convention
+ * lives here, outside the generated tree, in the one place that has to know it.
+ *
+ * The limits are the operation's own, generated from the server's policy, so a
+ * bad batch fails before any byte is uploaded and a valid one is never refused.
+ */
+/**
+ * The server trusts an explicit media type and only infers one, from the
+ * extension, for documents sent as octet-stream. Images are never inferred,
+ * so a screenshot has to arrive typed or it is refused.
+ */
+const MEDIA_TYPES = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.csv': 'text/csv',
+    '.tsv': 'text/tab-separated-values',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.svg': 'image/svg+xml',
+    '.yaml': 'application/x-yaml',
+    '.yml': 'application/x-yaml',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xls': 'application/vnd.ms-excel',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+};
+function mediaTypeFor(path) {
+    return MEDIA_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+function formatBytes(bytes) {
+    const mib = bytes / (1024 * 1024);
+    return Number.isInteger(mib) ? `${mib} MiB` : `${bytes}-byte`;
+}
+export function appendAttachments(form, paths, { maxFiles, maxBytes }) {
+    if (paths.length > maxFiles) {
+        throw new Error(`At most ${maxFiles} attachments per request; ${paths.length} given.`);
+    }
+    // Size from the inode before the read: a file past the cap must fail with
+    // this message, not with the runtime's own error once it has been loaded.
+    for (const path of paths) {
+        if (statSync(path).size > maxBytes) {
+            throw new Error(`${path} is larger than the ${formatBytes(maxBytes)} attachment limit.`);
+        }
+    }
+    const files = paths.map((path) => new File([readFileSync(path)], basename(path), { type: mediaTypeFor(path) }));
+    form.set('attachmentCount', String(files.length));
+    files.forEach((file, index) => form.set(`attachment_${index}`, file));
+}

package/dist/runtime/client.js

@@ -0,0 +1,188 @@
+import createClient, {} from 'openapi-fetch';
+import { version } from './version.js';
+const MAX_ATTEMPTS = 3;
+// A few hundred ms, growing: this sits in front of a human or agent waiting
+// on a command, so a real failure must not cost seconds.
+const RETRY_DELAYS_MS = [200, 400];
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Codes that can only be raised before any request bytes reach the server: a
+ * name that would not resolve, or a connection that was never accepted. Safe to
+ * retry whatever the method, because the server cannot have acted.
+ */
+const PRE_FLIGHT_CODES = ['EAI_AGAIN', 'ENOTFOUND', 'ECONNREFUSED'];
+/**
+ * Codes that can be raised at any point, including after the server has read
+ * the request and committed to it — a reset mid-response, an idle timeout on a
+ * pooled socket, an instance drained by a rolling deploy after its transaction
+ * landed. Indistinguishable from a pre-flight failure at this layer, so they
+ * are retried only where a repeat is harmless.
+ */
+const AMBIGUOUS_CODES = ['ECONNRESET', 'ETIMEDOUT'];
+/** No request body was ever sent twice for these, so a repeat cannot create anything. */
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+function methodOf(args) {
+    const [input, init] = args;
+    const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+    return method.toUpperCase();
+}
+/**
+ * Whether a repeat is harmless even if the first attempt reached the server.
+ * `markSeen` makes a GET a claim: the server moves the Seen Mark past the
+ * events it returns, so a repeat after a lost response claims the next ones
+ * and the lost events stay marked seen, never shown.
+ */
+function isRepeatable(args) {
+    if (!IDEMPOTENT_METHODS.has(methodOf(args)))
+        return false;
+    try {
+        const [input] = args;
+        const href = input instanceof Request ? input.url : String(input);
+        return new URL(href, 'http://localhost').searchParams.get('markSeen') !== 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function signalOf(args) {
+    const [input, init] = args;
+    return init?.signal ?? (input instanceof Request ? input.signal : undefined);
+}
+/**
+ * A sandbox VM resumed from pause can have a cold DNS resolver, which surfaces
+ * as a transport-level rejection rather than an HTTP error. An HTTP response is
+ * never retried — even a 500 is a definite answer, and `fetch` resolves rather
+ * than rejects for one, so that distinction falls out of catching here.
+ *
+ * What does NOT fall out of it is whether the server acted. `ECONNRESET` after
+ * a commit looks exactly like one before the connect, and `sessions create` is
+ * not idempotent: retrying it can leave a workspace paying for two sandboxes on
+ * one mention while the thread links only the second. So the ambiguous codes
+ * are retried on repeatable requests only, and anything else gets a retry only
+ * when the failure provably precedes the request.
+ */
+function isRetryable(error, repeatable) {
+    // An abort or a timeout says the client stopped waiting, never that the
+    // server stopped working — the write may already have landed.
+    const name = error instanceof Error ? error.name : undefined;
+    if (name === 'AbortError' || name === 'TimeoutError')
+        return repeatable;
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause instanceof Error ? cause.code : undefined;
+    if (!code)
+        return false;
+    if (PRE_FLIGHT_CODES.includes(code))
+        return true;
+    return repeatable && AMBIGUOUS_CODES.includes(code);
+}
+function withTransportRetry(fetchImpl) {
+    return async (...args) => {
+        let attempt = 0;
+        for (;;) {
+            attempt++;
+            try {
+                return await fetchImpl(...args);
+            }
+            catch (error) {
+                if (attempt >= MAX_ATTEMPTS)
+                    throw error;
+                // The caller's own signal fired: it stopped waiting, and a repeat would only fail again.
+                if (signalOf(args)?.aborted)
+                    throw error;
+                if (!isRetryable(error, isRepeatable(args)))
+                    throw error;
+                // Safe: the guard above ensures attempt is within [1, MAX_ATTEMPTS - 1] here.
+                await sleep(RETRY_DELAYS_MS[attempt - 1]);
+            }
+        }
+    };
+}
+/** Where Node's fetch, and the `undici` package beside it, keep the dispatcher every request uses. */
+const GLOBAL_DISPATCHER = Symbol.for('undici.globalDispatcher.1');
+function globalDispatcher() {
+    return globalThis[GLOBAL_DISPATCHER];
+}
+/**
+ * Node's fetch gives up on an answer after 300 s, undici's `headersTimeout` and `bodyTimeout`,
+ * whatever signal the caller set. Each request here sets both for itself and goes on through the
+ * dispatcher Node already uses, rather than a new one, so a proxy that `NODE_USE_ENV_PROXY` set
+ * up, as in Sensei, still carries it.
+ */
+function withAnswerTimeout(fetchImpl, timeoutMs) {
+    const dispatcher = {
+        dispatch(options, handler) {
+            return globalDispatcher().dispatch({ ...options, headersTimeout: timeoutMs, bodyTimeout: timeoutMs }, handler);
+        },
+    };
+    return (input, init) => {
+        // Another runtime has no such dispatcher, and keeps its own limits.
+        if (!globalDispatcher())
+            return fetchImpl(input, init);
+        // Node's own `Dispatcher` type is undici's whole class; fetch calls only `dispatch`.
+        return fetchImpl(input, { ...init, dispatcher });
+    };
+}
+/** The most of one integration answer the CLI reads; its listings are bounded well below it. */
+const MAX_INTEGRATION_RESPONSE_BYTES = 512 * 1024;
+const INTEGRATIONS_PREFIX = '/api/agent-integrations/';
+/** An integration answer past the cap; a call that got one may still have run. */
+export class ResponseTooLarge extends Error {
+    constructor() {
+        super('Integration response was too large');
+        this.name = 'ResponseTooLarge';
+    }
+}
+/**
+ * Caps what an integration route can make the CLI buffer, error bodies included. The body is
+ * counted as it streams, so nothing past the cap is held or parsed. Other routes are untouched.
+ */
+function withIntegrationCap(fetchImpl) {
+    return async (...args) => {
+        const response = await fetchImpl(...args);
+        const [input] = args;
+        try {
+            const href = input instanceof Request ? input.url : String(input);
+            if (!new URL(href, 'http://localhost').pathname.startsWith(INTEGRATIONS_PREFIX)) {
+                return response;
+            }
+        }
+        catch {
+            return response;
+        }
+        if (!response.body)
+            return response;
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > MAX_INTEGRATION_RESPONSE_BYTES) {
+            await response.body.cancel().catch(() => undefined);
+            throw new ResponseTooLarge();
+        }
+        let total = 0;
+        const counted = response.body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                total += chunk.byteLength;
+                if (total > MAX_INTEGRATION_RESPONSE_BYTES)
+                    controller.error(new ResponseTooLarge());
+                else
+                    controller.enqueue(chunk);
+            },
+        }));
+        return new Response(counted, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+}
+export function createApiClient({ apiUrl, apiKey, fetch, answerTimeoutMs, }) {
+    const base = fetch ?? globalThis.fetch;
+    return createClient({
+        baseUrl: apiUrl,
+        headers: {
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            'User-Agent': `@kosuke-ai/kosuke/${version}`,
+        },
+        fetch: withIntegrationCap(withTransportRetry(answerTimeoutMs === undefined ? base : withAnswerTimeout(base, answerTimeoutMs))),
+    });
+}

package/dist/runtime/config.js

@@ -0,0 +1,49 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_API_URL = 'https://app.kosuke.ai';
+function configDir(env = process.env) {
+    if (env.KOSUKE_CONFIG_DIR)
+        return env.KOSUKE_CONFIG_DIR;
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, 'kosuke');
+    if (process.platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, 'kosuke');
+    return join(homedir(), '.config', 'kosuke');
+}
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), 'credentials.json');
+}
+export function readCredentials(env = process.env) {
+    try {
+        const parsed = JSON.parse(readFileSync(credentialsPath(env), 'utf8'));
+        if (parsed && typeof parsed === 'object' && 'apiKey' in parsed) {
+            const { apiKey, apiUrl } = parsed;
+            if (typeof apiKey === 'string' && apiKey.length > 0) {
+                return { apiKey, ...(typeof apiUrl === 'string' ? { apiUrl } : {}) };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(credentials, null, 2) + '\n', { mode: 0o600 });
+    // `mode` on write only applies to a file being created; an existing one keeps
+    // whatever it had, and a token file must not.
+    chmodSync(path, 0o600);
+    return path;
+}
+export function deleteCredentials(env = process.env) {
+    try {
+        rmSync(credentialsPath(env));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime/credentials.js

@@ -0,0 +1,32 @@
+import { agentTokenOf } from './agent-tokens.js';
+import { DEFAULT_API_URL, readCredentials } from './config.js';
+/**
+ * A credential that needs no `--workspace`: a sandbox or cron token decides its
+ * workspace, and a Sensei token reaches its member's own connections without one.
+ */
+export function isTurnToken(token) {
+    return agentTokenOf(token) !== null;
+}
+export function resolveCredentials(flags, env = process.env) {
+    const stored = readCredentials(env);
+    const apiKey = flags.apiKey
+        ? { value: flags.apiKey, source: 'flag' }
+        : env.KOSUKE_API_KEY
+            ? { value: env.KOSUKE_API_KEY, source: 'env' }
+            : stored
+                ? { value: stored.apiKey, source: 'file' }
+                : null;
+    const apiUrl = flags.apiUrl
+        ? { value: flags.apiUrl, source: 'flag' }
+        : env.KOSUKE_API_URL
+            ? { value: env.KOSUKE_API_URL, source: 'env' }
+            : stored?.apiUrl
+                ? { value: stored.apiUrl, source: 'file' }
+                : { value: DEFAULT_API_URL, source: 'default' };
+    return {
+        apiKey: apiKey?.value ?? null,
+        apiKeySource: apiKey?.source ?? null,
+        apiUrl: apiUrl.value.replace(/\/+$/, ''),
+        apiUrlSource: apiUrl.source,
+    };
+}

package/dist/runtime/descriptor.js

@@ -0,0 +1,7 @@
+/**
+ * What the generator writes per operation, and what the runtime builds a
+ * command from. Data only: the generated tree holds no logic, so it stays
+ * small, byte-stable and reviewable, and every behaviour lives in one
+ * hand-written place.
+ */
+export {};