@kosuke-ai/kosuke 1.0.0 → 1.0.2

package/dist/runtime/invoke.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { appendAttachments } from './attachments.js';
+export class UsageError extends Error {
+}
+export function buildRequest(operation, input) {
+    const queryNames = new Set(operation.query.map((field) => field.name));
+    const query = {};
+    for (const field of operation.query) {
+        const value = input.fields[field.name];
+        if (value !== undefined)
+            query[field.name] = value;
+    }
+    for (const field of operation.query) {
+        if (field.required && query[field.name] === undefined) {
+            throw new UsageError(`--${field.flag} is required.`);
+        }
+    }
+    const bodyFields = Object.fromEntries(Object.entries(input.fields).filter(([name, value]) => !queryNames.has(name) && value !== undefined));
+    return {
+        method: operation.method,
+        path: operation.path,
+        pathParams: input.pathParams,
+        query,
+        body: buildBody(operation, bodyFields, input),
+    };
+}
+/**
+ * Which media type to send. Multipart when the operation only takes that, when
+ * files are attached, or when a field given exists only on the form branch;
+ * JSON otherwise, including an empty `{}` for a body-taking operation given
+ * nothing, which is how the deploy route reads "start a deploy".
+ */
+function buildBody(operation, fields, input) {
+    const takesJson = operation.body !== null;
+    const takesMultipart = operation.multipart !== null;
+    if (!takesJson && !takesMultipart) {
+        if (input.wholeBody !== undefined || Object.keys(fields).length || input.attachments.length) {
+            throw new UsageError(`kosuke ${operation.command.join(' ')} takes no body.`);
+        }
+        return null;
+    }
+    if (input.attachments.length && !operation.attachments) {
+        throw new UsageError(`kosuke ${operation.command.join(' ')} takes no attachments.`);
+    }
+    // The keys that decide the media type come from --body as much as from the
+    // flags: `--body '{"content":"hi"}'` on the deploy route names a form-only
+    // field, and sending it as JSON would have zod strip it and the handler read
+    // an empty body, which there means "start a fresh deploy".
+    const jsonFields = operation.body?.fields ?? null;
+    const jsonNames = new Set(jsonFields?.map((field) => field.name) ?? []);
+    // A field flag always names a field of one branch, so it decides on its
+    // own. The keys of --body decide only against a flat JSON body: a non-flat
+    // one (an array, a union) has no field names to hold them against, and
+    // sending such a --body as the form would be a guess. No operation has that
+    // shape beside a form branch today; if one does, --body stays JSON there.
+    const given = [
+        ...Object.keys(fields),
+        ...(jsonFields ? Object.keys(asRecordOrEmpty(input.wholeBody)) : []),
+    ];
+    const multipartOnly = given.some((name) => !jsonNames.has(name));
+    const useMultipart = takesMultipart && (!takesJson || input.attachments.length > 0 || multipartOnly);
+    if (useMultipart) {
+        const form = new FormData();
+        const source = input.wholeBody !== undefined ? asRecord(input.wholeBody, 'The body') : fields;
+        const known = new Map((operation.multipart ?? []).map((field) => [field.name, field]));
+        for (const [name, value] of Object.entries(source)) {
+            if (!known.has(name))
+                throw new UsageError(`Unknown form field "${name}".`);
+            if (value === undefined || value === null)
+                continue;
+            form.set(name, formValue(value));
+        }
+        for (const field of operation.multipart ?? []) {
+            if (field.required && !form.has(field.name)) {
+                throw new UsageError(`--${field.flag} is required.`);
+            }
+        }
+        if (input.attachments.length && operation.attachments)
+            appendAttachments(form, input.attachments, operation.attachments);
+        return { kind: 'multipart', value: form };
+    }
+    if (input.wholeBody !== undefined)
+        return { kind: 'json', value: input.wholeBody };
+    if (operation.body?.fields === null) {
+        if (Object.keys(fields).length) {
+            throw new UsageError(`This body is not a flat object; pass it whole with --body, --body-file or on stdin.`);
+        }
+        if (operation.body.required) {
+            throw new UsageError(`A body is required: pass --body, or --body-file with a path or - for stdin.`);
+        }
+        return null;
+    }
+    for (const field of operation.body?.fields ?? []) {
+        if (field.required && fields[field.name] === undefined) {
+            throw new UsageError(`--${field.flag} is required.`);
+        }
+    }
+    return { kind: 'json', value: fields };
+}
+/**
+ * A form field is a string. A value already parsed as JSON (an object from a
+ * `json` flag, or from --body) goes back to its text, which is what the
+ * handler JSON-parses on the form branch; scalars go as they print.
+ */
+function formValue(value) {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function asRecordOrEmpty(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asRecord(value, what) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    throw new UsageError(`${what} must be a JSON object for a multipart request.`);
+}
+/**
+ * `--body '<json>'`, or `--body-file <path>` with `-` for stdin. Stdin is read
+ * only when asked for: a CLI that reads an inherited pipe on its own hangs
+ * whenever the parent never closes it, which is a bug that only shows up in
+ * someone else's script.
+ */
+export function readWholeBody(options, readStdin = () => readFileSync(0, 'utf8')) {
+    let text = null;
+    if (options.body !== undefined)
+        text = options.body;
+    else if (options.bodyFile === '-')
+        text = readStdin();
+    else if (options.bodyFile !== undefined)
+        text = readFileSync(options.bodyFile, 'utf8');
+    if (text === null || text.trim() === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('The body is not valid JSON.');
+    }
+}
+export async function execute(client, request) {
+    const init = {
+        params: { path: request.pathParams, query: request.query },
+    };
+    if (request.body)
+        init.body = request.body.value;
+    // `request()` rather than the typed verbs: the descriptor decides the path at
+    // run time, and openapi-fetch's per-path types cannot follow a variable.
+    const { data, error, response } = await client.request(request.method, request.path, init);
+    return { ok: response.ok, status: response.status, body: response.ok ? data : error };
+}

package/dist/runtime/job-watch.js

@@ -0,0 +1,374 @@
+/**
+ * Following one job's `/ws/jobs` stream to its end: the socket, the resume
+ * cursor, the close codes and the status fallback, with everything that
+ * touches the process or the network handed in, so each path is testable
+ * without either. `kosuke sessions watch` is its one caller.
+ */
+export const JOB_TYPES = ['chat', 'deploy'];
+export const WATCH_EXIT = {
+    ended: 0,
+    failed: 1,
+    unauthorized: 3,
+    notFound: 4,
+    // What coreutils `timeout` exits with, so one check in a script reads both.
+    timedOut: 124,
+};
+/**
+ * The statuses a job never leaves, and whether each counts as a success. The
+ * two awaiting ones are a turn that ended by asking the member a question: the
+ * worker closes that stream with a successful `done`, so the fallback agrees.
+ */
+const ENDINGS = {
+    chat: new Map([
+        ['completed', true],
+        ['awaiting_response', true],
+        ['failed', false],
+        ['cancelled', false],
+    ]),
+    deploy: new Map([
+        ['deployed', true],
+        ['awaiting_user', true],
+        ['failed', false],
+        ['cancelled', false],
+    ]),
+};
+const POLL_INTERVAL_MS = 5_000;
+/**
+ * How long a job status that says it ended waits for the stream to say so too,
+ * counted from the stream's last frame so a replay is not cut off halfway.
+ * The worker writes the status before it publishes `done`, so ending on the
+ * status at once could cut off the last frames of a turn still being delivered.
+ * A cancelled chat turn publishes no `done` at all, so this is its only ending.
+ */
+const SETTLE_GRACE_MS = 3_000;
+/**
+ * Without --timeout, the most a watch spends reconnecting to read the stream to
+ * its end once the status says the job ended. A stream that cannot be reached
+ * must not hold it forever, so past this it ends on the status, incomplete.
+ */
+const SETTLE_LIMIT_MS = 15_000;
+/** How long one platform read may take; fetch alone would wait minutes. */
+const READ_LIMIT_MS = 10_000;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+/**
+ * Follow one job to its end and resolve with the exit code. Stdout gets frames
+ * and nothing else: the platform's own, then `watch.status` when the watched
+ * turn's own status rather than the stream ended the watch, then `watch.links`
+ * whenever the job ended. Everything a person reads goes to stderr.
+ */
+export function watchJob(options, deps) {
+    const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const settleGraceMs = options.settleGraceMs ?? SETTLE_GRACE_MS;
+    const deadline = options.timeoutMs ? Date.now() + options.timeoutMs : null;
+    return new Promise((resolve) => {
+        // Redis stream ids: the server reads strictly after this, so a reconnect
+        // carrying the last id seen neither repeats a frame nor skips one.
+        let cursor = '0';
+        let generation = 0;
+        let socket = null;
+        let connected = false;
+        let failures = 0;
+        let finished = false;
+        let lastPollProblem = null;
+        let polling = false;
+        let nextPoll = null;
+        let reconnect = null;
+        // Why a deploy's stream refused the watch after its turn released it.
+        let streamGone = null;
+        // How the watch ends once the status says the job ended, unless the stream
+        // ends it first.
+        let ending = null;
+        let quiet = null;
+        const timers = new Set();
+        const reads = new Set();
+        const later = (ms, run) => {
+            const timer = setTimeout(() => {
+                timers.delete(timer);
+                run();
+            }, ms);
+            timers.add(timer);
+            return timer;
+        };
+        const cancel = (timer) => {
+            if (timer === null)
+                return;
+            clearTimeout(timer);
+            timers.delete(timer);
+        };
+        /** Settles with `read`, or rejects with `why` once `ms` pass, aborting its request. */
+        const bounded = (ms, why, read) => {
+            const controller = new AbortController();
+            reads.add(controller);
+            const timer = setTimeout(() => controller.abort(new Error(why)), ms);
+            const abandoned = new Promise((_, reject) => {
+                controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+            });
+            return Promise.race([read(controller.signal), abandoned]).finally(() => {
+                clearTimeout(timer);
+                reads.delete(controller);
+            });
+        };
+        const end = async (code, jobEnded) => {
+            if (finished)
+                return;
+            finished = true;
+            for (const timer of timers)
+                clearTimeout(timer);
+            timers.clear();
+            // A reason that is not an AbortError, which the client's retry would retry.
+            for (const read of reads)
+                read.abort(new Error('the watch ended'));
+            socket?.close(1000, 'watch ended');
+            socket = null;
+            if (jobEnded) {
+                // Clearing the timers took the timeout with them, so the links get
+                // what was left of it.
+                const left = deadline === null ? READ_LIMIT_MS : deadline - Date.now();
+                const why = left < READ_LIMIT_MS ? 'the timeout passed' : `no answer after ${READ_LIMIT_MS / 1000}s`;
+                try {
+                    const links = await bounded(Math.max(0, Math.min(left, READ_LIMIT_MS)), why, deps.readLinks);
+                    deps.stdout(JSON.stringify({ type: 'watch.links', data: links }));
+                }
+                catch (error) {
+                    deps.stderr(`kosuke: could not read the links: ${describe(error)}`);
+                }
+            }
+            resolve(code);
+        };
+        /** End on the status. `gap` says why the stream could not be read to its end. */
+        const conclude = (gap) => {
+            if (finished || ending === null)
+                return;
+            if (gap !== null) {
+                deps.stderr(`kosuke: could not read the stream after frame ${cursor} (${gap}); frames after it may be missing.`);
+            }
+            if (ending.status) {
+                const data = { ...ending.status, complete: gap === null };
+                deps.stdout(JSON.stringify({ type: 'watch.status', data }));
+            }
+            if (ending.note)
+                deps.stderr(ending.note);
+            void end(ending.code, true);
+        };
+        const awaitQuiet = () => {
+            cancel(quiet);
+            quiet = later(settleGraceMs, () => conclude(null));
+        };
+        // The stream still holds what was published after the cursor, so the watch
+        // reconnects until its replay drains, bounded by --timeout or else the
+        // settle limit. The backoff starts over, so a stream that comes back soon
+        // is read before that bound passes.
+        const beginEnding = (next) => {
+            ending = next;
+            failures = 0;
+            if (deadline === null) {
+                later(SETTLE_LIMIT_MS, () => conclude(`${SETTLE_LIMIT_MS / 1000}s passed after the job ended`));
+            }
+            if (connected) {
+                awaitQuiet();
+            }
+            else if (streamGone !== null) {
+                conclude(streamGone);
+            }
+            else if (socket === null) {
+                cancel(reconnect);
+                deps.stderr(`kosuke: reconnecting after frame ${cursor} now, to read what the stream holds.`);
+                connect();
+            }
+        };
+        const onFrame = (text) => {
+            let frame;
+            try {
+                frame = JSON.parse(text);
+            }
+            catch {
+                deps.stderr('kosuke: skipped a frame that is not JSON.');
+                return;
+            }
+            if (!isRecord(frame)) {
+                deps.stderr('kosuke: skipped a frame that is not a JSON object.');
+                return;
+            }
+            // The platform's own text; one spread over lines is compacted so it
+            // still reads as one line to `jq`.
+            deps.stdout(/[\r\n]/.test(text) ? JSON.stringify(frame) : text);
+            if (typeof frame.id === 'string')
+                cursor = frame.id;
+            const data = isRecord(frame.data) ? frame.data : {};
+            if (frame.type === 'done') {
+                void end(data.success === false ? WATCH_EXIT.failed : WATCH_EXIT.ended, true);
+            }
+            else if (frame.type === 'error' && data.recoverable !== true) {
+                // A deploy reports a recoverable error and carries on to its own `done`.
+                void end(WATCH_EXIT.failed, true);
+            }
+            else if (ending) {
+                awaitQuiet();
+            }
+        };
+        const onClose = (code, reason) => {
+            socket = null;
+            connected = false;
+            cancel(quiet);
+            const why = `${code} ${reason || 'no reason given'}`;
+            // /ws/jobs matches a deploy by the stream its turn holds, which the worker
+            // releases as the turn ends. A stream that has delivered frames existed,
+            // so its 4404 means the turn is over, and the status says how it ended.
+            if (code === 4404 && options.jobType === 'deploy' && cursor !== '0') {
+                streamGone = why;
+                if (ending)
+                    return conclude(why);
+                deps.stderr(`kosuke: the stream closed (${why}); reading the Deploy's status.`);
+                pollNow();
+                return;
+            }
+            const refused = refusalExit(code);
+            if (refused !== null) {
+                deps.stderr(`kosuke: the platform refused the stream: ${why}`);
+                void end(refused, false);
+                return;
+            }
+            failures += 1;
+            const delay = Math.min(RECONNECT_BASE_MS * 2 ** (failures - 1), RECONNECT_MAX_MS);
+            deps.stderr(`kosuke: the stream closed (${why}); reconnecting after frame ${cursor} in ${delay / 1000}s.`);
+            reconnect = later(delay, connect);
+        };
+        const connect = () => {
+            const mine = ++generation;
+            // A socket this watch has moved on from, or finished with, is not heard.
+            const current = () => !finished && mine === generation;
+            let opened = null;
+            try {
+                opened = deps.connect(streamUrl(options, cursor), {
+                    open: () => {
+                        if (!current())
+                            return;
+                        failures = 0;
+                        connected = true;
+                        opened?.send(JSON.stringify({ type: 'auth', token: options.apiKey }));
+                        if (ending)
+                            awaitQuiet();
+                    },
+                    message: (text) => {
+                        if (current())
+                            onFrame(text);
+                    },
+                    close: (code, reason) => {
+                        if (current())
+                            onClose(code, reason);
+                    },
+                });
+                socket = opened;
+            }
+            catch (error) {
+                deps.stderr(`kosuke: could not open the stream: ${describe(error)}`);
+                void end(WATCH_EXIT.failed, false);
+            }
+        };
+        const schedulePoll = () => {
+            nextPoll = later(pollIntervalMs, () => void poll());
+        };
+        const pollNow = () => {
+            if (polling || ending)
+                return;
+            cancel(nextPoll);
+            void poll();
+        };
+        const poll = async () => {
+            polling = true;
+            let reading;
+            try {
+                reading = await bounded(READ_LIMIT_MS, `no answer after ${READ_LIMIT_MS / 1000}s`, deps.checkStatus);
+            }
+            catch (error) {
+                reading = { ok: false, httpStatus: null, message: describe(error) };
+            }
+            polling = false;
+            if (finished)
+                return;
+            if (!reading.ok) {
+                const refused = reading.httpStatus === 401 || reading.httpStatus === 403
+                    ? WATCH_EXIT.unauthorized
+                    : reading.httpStatus === 404
+                        ? WATCH_EXIT.notFound
+                        : null;
+                if (refused !== null) {
+                    deps.stderr(`kosuke: could not read the job: ${reading.message}`);
+                    void end(refused, false);
+                    return;
+                }
+                // Once per distinct problem: an outage would otherwise print every 5 s.
+                if (reading.message !== lastPollProblem) {
+                    deps.stderr(`kosuke: could not read the job status (${reading.message}); still watching.`);
+                }
+                lastPollProblem = reading.message;
+                schedulePoll();
+                return;
+            }
+            lastPollProblem = null;
+            if ('movedOn' in reading) {
+                beginEnding({
+                    code: WATCH_EXIT.failed,
+                    status: null,
+                    note: `kosuke: ${reading.movedOn}, so how this turn ended cannot be read.`,
+                });
+                return;
+            }
+            const success = ENDINGS[options.jobType].get(reading.status);
+            if (success === undefined) {
+                schedulePoll();
+                return;
+            }
+            const { status, error, errorCode } = reading;
+            beginEnding({
+                code: success ? WATCH_EXIT.ended : WATCH_EXIT.failed,
+                status: { status, error, errorCode },
+                note: null,
+            });
+        };
+        if (options.timeoutMs) {
+            const seconds = options.timeoutMs / 1000;
+            later(options.timeoutMs, () => {
+                // The job did end: the timeout only cut short reading its stream.
+                if (ending)
+                    return conclude('the timeout passed');
+                deps.stderr(`kosuke: stopped waiting after ${seconds}s; the job had not ended.`);
+                void end(WATCH_EXIT.timedOut, false);
+            });
+        }
+        connect();
+        schedulePoll();
+    });
+}
+/**
+ * 4400-4499 is the server's permanent refusal: bad params, a refused token, no
+ * access, nothing to watch. Retrying any of them would loop forever.
+ */
+function refusalExit(code) {
+    if (code < 4400 || code > 4499)
+        return null;
+    if (code === 4401 || code === 4403)
+        return WATCH_EXIT.unauthorized;
+    if (code === 4404)
+        return WATCH_EXIT.notFound;
+    return WATCH_EXIT.failed;
+}
+function streamUrl(options, lastId) {
+    const url = new URL('/ws/jobs', options.apiUrl);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
+    url.search = new URLSearchParams({
+        projectId: options.projectId,
+        sessionId: options.sessionId,
+        jobType: options.jobType,
+        jobId: options.jobId,
+        lastId,
+    }).toString();
+    return url.toString();
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runtime/runtime.js

@@ -0,0 +1,46 @@
+import { createApiClient } from './client.js';
+import { resolveCredentials, } from './credentials.js';
+export function createRuntime({ flags, env = process.env, fetch, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+    process.exitCode = code;
+}, }) {
+    let resolved = null;
+    const credentials = () => (resolved ??= resolveCredentials(flags, env));
+    return {
+        credentials,
+        client({ anonymous = false, answerTimeoutMs } = {}) {
+            const { apiKey, apiUrl } = credentials();
+            if (!apiKey && !anonymous) {
+                stderr('No API key. Run `kosuke auth login`, set KOSUKE_API_KEY, or pass --api-key. ' +
+                    'Create one in Settings on the platform.');
+                exit(1);
+                throw new ExitSignal();
+            }
+            return createApiClient({
+                apiUrl,
+                apiKey: anonymous ? null : apiKey,
+                fetch,
+                answerTimeoutMs,
+            });
+        },
+        output(outcome) {
+            if (outcome.ok) {
+                // 204 has nothing to print; anything else is passed through as JSON so
+                // `| jq` works without the platform CLI knowing the shape.
+                if (outcome.body !== undefined)
+                    stdout(render(outcome.body));
+                return;
+            }
+            stderr(render(outcome.body ?? { error: `HTTP ${outcome.status}` }));
+            exit(1);
+        },
+    };
+}
+function render(body) {
+    return typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+}
+/** Thrown after `exit` so the action stops without printing a second error. */
+export class ExitSignal extends Error {
+    constructor() {
+        super('exit');
+    }
+}

package/dist/runtime/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+// Read at run time rather than imported with an attribute: the package's own
+// manifest ships with it, and this works the same from src/ and from dist/.
+const manifest = createRequire(import.meta.url)('../../package.json');
+export const version = manifest.version;