@kosuke-ai/kosuke 1.0.0 → 1.0.1

package/dist/commands/watch.js

@@ -0,0 +1,167 @@
+import { InvalidArgumentError, Option } from 'commander';
+import { groupFor } from '../runtime/attach.js';
+import { JOB_TYPES, WATCH_EXIT, describe, isRecord, watchJob, } from '../runtime/job-watch.js';
+/**
+ * `kosuke sessions watch`: a turn's frames as they happen, one JSON object per
+ * line. Hand-written because they arrive over the `/ws/jobs` WebSocket, which
+ * the OpenAPI document the rest of the tree is generated from cannot describe.
+ */
+/** Node's own WebSocket; `engines` guarantees a Node that has it. */
+const openWebSocket = (url, on) => {
+    const socket = new WebSocket(url);
+    socket.binaryType = 'arraybuffer';
+    socket.addEventListener('open', () => on.open());
+    socket.addEventListener('message', (event) => {
+        const data = event.data;
+        on.message(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'));
+    });
+    // Every failure, a refused upgrade included, reaches 'close' with a code;
+    // 'error' carries nothing more.
+    socket.addEventListener('close', (event) => on.close(event.code, event.reason));
+    return {
+        send: (text) => socket.send(text),
+        close: (code, reason) => socket.close(code, reason),
+    };
+};
+/**
+ * Reads the watched job's status. The deploy messages report the project's
+ * latest Deploy, whose status is the outcome of the turn `lastStreamId` names:
+ * the watched turn's only while it names that one. A Deploy row from before the
+ * platform named its last turn has none, and then the reader falls back to the
+ * Deploy it saw the watched turn running in.
+ */
+function statusReader(client, target) {
+    const { projectId, sessionId, jobId } = target;
+    // The Deploy the watched turn ran in, once a reading showed it running.
+    let deployId = null;
+    return async (signal) => {
+        try {
+            if (target.jobType === 'deploy') {
+                const { data, error, response } = await client.GET('/api/projects/{projectId}/deploy-messages', { params: { path: { projectId } }, signal });
+                if (!response.ok)
+                    return refused(response.status, error);
+                const body = record(record(data).data);
+                const liveTurn = text(body.activeStreamId);
+                const readDeploy = text(body.deployJobId);
+                if (liveTurn === jobId)
+                    deployId = readDeploy;
+                if (liveTurn !== null && liveTurn !== jobId) {
+                    return { ok: true, movedOn: `the Deploy moved on to turn ${liveTurn}` };
+                }
+                const lastTurn = text(body.lastStreamId);
+                if (lastTurn !== null && lastTurn !== jobId) {
+                    return { ok: true, movedOn: `the Deploy moved on to turn ${lastTurn}` };
+                }
+                if (lastTurn === null && deployId !== null && readDeploy !== deployId) {
+                    return { ok: true, movedOn: 'a later Deploy replaced this one' };
+                }
+                return { ok: true, status: String(body.status), error: text(body.error), errorCode: null };
+            }
+            const { data, error, response } = await client.GET('/api/projects/{projectId}/chat-sessions/{sessionId}/jobs/chat/{jobId}', { params: { path: { projectId, sessionId, jobId } }, signal });
+            if (!response.ok)
+                return refused(response.status, error);
+            const job = record(record(record(data).data).job);
+            return {
+                ok: true,
+                status: String(job.status),
+                error: text(job.error),
+                errorCode: text(job.errorCode),
+            };
+        }
+        catch (error) {
+            return { ok: false, httpStatus: null, message: describe(error) };
+        }
+    };
+}
+/**
+ * Where to look at what the job produced. Built from the platform's own routes
+ * rather than read from `preview get`, which starts a paused sandbox: a watch
+ * on a job that ended an hour ago must not start billing for one.
+ */
+async function readLinks(client, apiUrl, target, stderr, signal) {
+    const project = `${apiUrl}/projects/${encodeURIComponent(target.projectId)}`;
+    if (target.jobType === 'deploy') {
+        // No preview link: members do not see the main sandbox's Preview.
+        return { deploy: `${project}?view=settings` };
+    }
+    const session = `${project}/chat-sessions?session=${encodeURIComponent(target.sessionId)}`;
+    let pullRequest = null;
+    try {
+        const { data, error, response } = await client.GET('/api/projects/{projectId}/chat-sessions/{sessionId}', { params: { path: { projectId: target.projectId, sessionId: target.sessionId } }, signal });
+        if (response.ok) {
+            pullRequest = text(record(record(data).data).prUrl);
+        }
+        else {
+            const { message } = refused(response.status, error);
+            stderr(`kosuke: could not read the pull request: ${message}`);
+        }
+    }
+    catch (error) {
+        // Aborted: the watch stopped waiting and says so itself.
+        if (signal.aborted)
+            throw error;
+        stderr(`kosuke: could not read the pull request: ${describe(error)}`);
+    }
+    return { session, preview: `${session}&tab=preview`, pullRequest };
+}
+function refused(status, error) {
+    const message = text(record(error).error) ?? `HTTP ${status}`;
+    return { ok: false, httpStatus: status, message };
+}
+export function attachWatchCommand(root, runtime, deps = {}) {
+    const { connect = openWebSocket, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+        process.exitCode = code;
+    }, } = deps;
+    groupFor(root, ['sessions'])
+        .command('watch')
+        .description("Stream a turn's frames as NDJSON until its job ends: one frame per line on stdout, " +
+        'diagnostics on stderr. A dropped connection resumes after the last frame, and the ' +
+        "job's status is read every 5 s, so a stream that goes quiet still ends.")
+        .argument('<projectId>', 'Project id')
+        .argument('<sessionId>', 'Session id. Not read for --type deploy, which is per project.')
+        .argument('<jobId>', "The turn's chat job id. For --type deploy, the activeStreamId `kosuke deploy messages` returns.")
+        .addOption(new Option('--type <type>', 'What the job is.').choices(JOB_TYPES).default('chat'))
+        .option('--timeout <seconds>', 'Stop waiting after this many seconds and exit 124. Default: until the job ends.', seconds)
+        .addHelpText('after', '\nFrames from the platform carry an id. Two more, without one, come from this command:\n' +
+        "  watch.status  the job's status, when that rather than the stream ended the watch;\n" +
+        '                its complete is false when frames after the last one may be missing\n' +
+        '  watch.links   last, once the job ended: where to see what it produced\n' +
+        '\nExit codes:\n' +
+        '  0    the job ended well\n' +
+        '  1    it failed or was stopped, or how a deploy turn ended could not be read\n' +
+        '  3    the API key was refused\n' +
+        '  4    the project, session or job was not found\n' +
+        '  124  --timeout passed first')
+        .action(async (projectId, sessionId, jobId, flags) => {
+        // First, so a missing API key fails with the message every command gives.
+        const client = runtime.client();
+        const { apiKey, apiUrl } = runtime.credentials();
+        const target = { projectId, sessionId, jobId, jobType: flags.type };
+        const code = await watchJob({
+            ...target,
+            apiUrl,
+            apiKey: apiKey,
+            ...(flags.timeout ? { timeoutMs: flags.timeout * 1000 } : {}),
+        }, {
+            connect,
+            checkStatus: statusReader(client, target),
+            readLinks: (signal) => readLinks(client, apiUrl, target, stderr, signal),
+            stdout,
+            stderr,
+        });
+        if (code !== WATCH_EXIT.ended)
+            exit(code);
+    });
+}
+function seconds(raw) {
+    if (!/^\d+$/.test(raw) || Number(raw) === 0) {
+        throw new InvalidArgumentError('Expected a whole number of seconds above 0.');
+    }
+    return Number(raw);
+}
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function text(value) {
+    return typeof value === 'string' && value ? value : null;
+}

package/dist/generated/commands/activity/list.js

@@ -0,0 +1,73 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/activity",
+    "command": [
+        "activity",
+        "list"
+    ],
+    "summary": "List Activity across every workspace you belong to, newest first: Changes Kosuke observed and what members did. Each event names its workspace. An agent token reads its own workspace only.",
+    "pathParams": [],
+    "query": [
+        {
+            "name": "since",
+            "flag": "since",
+            "kind": "string",
+            "required": false,
+            "description": "Only events at or after this time: an ISO date or time, or a span back from now such as 24h or 7d."
+        },
+        {
+            "name": "unseen",
+            "flag": "unseen",
+            "kind": "boolean",
+            "required": false,
+            "description": "Only New events: after your Seen Mark and not your own. Returned oldest first, so --limit takes the earliest."
+        },
+        {
+            "name": "markSeen",
+            "flag": "mark-seen",
+            "kind": "boolean",
+            "required": false,
+            "description": "Return your New events, oldest first, and mark them seen in the same call, so no event comes back twice. Implies unseen; refused with project, kind or since, which would mark events you were not shown. Needs an API key: refused for a browser session."
+        },
+        {
+            "name": "workspace",
+            "flag": "workspace",
+            "kind": "string",
+            "required": false,
+            "description": "Only this workspace. Refused with 403 when you are not a member of it."
+        },
+        {
+            "name": "project",
+            "flag": "project",
+            "kind": "string",
+            "required": false,
+            "description": "Only this project, by id."
+        },
+        {
+            "name": "kind",
+            "flag": "kind",
+            "kind": "string",
+            "required": false,
+            "description": "Comma-separated kinds (job_awaiting_response, pr_checks_failed, pr_checks_passed, pr_merged, branch_behind, pr_stale, cron_run_succeeded, cron_run_failed, deployed, recovery_deploy_started, session_started, session_message_sent, session_archived, session_deleted, session_assigned, session_status_changed, session_priority_changed, cron_created, cron_updated, cron_deleted, member_invited, member_removed, member_role_changed, integration_custom_tool_saved, integration_custom_tool_enabled, integration_custom_tool_disabled, integration_custom_tool_deleted, integration_custom_tool_restored), or 'change' for every Change and 'action' for every Member Action."
+        },
+        {
+            "name": "limit",
+            "flag": "limit",
+            "kind": "integer",
+            "required": false,
+            "description": "Page size, 50 by default. Values above 200 are clamped, not rejected."
+        },
+        {
+            "name": "cursor",
+            "flag": "cursor",
+            "kind": "string",
+            "required": false,
+            "description": "Cursor from a previous page (meta.pagination.nextCursor). Not used with markSeen."
+        }
+    ],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/artifacts-list.js

@@ -0,0 +1,57 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/artifacts",
+    "command": [
+        "crons",
+        "artifacts",
+        "list"
+    ],
+    "summary": "List the Artifacts a cron's runs published, across all of its runs, most recently changed first: each one's title, kind and version, with the run and the project it came from, and the total the filters keep. One row per Artifact: the same slug published by two runs is two rows. Rows only: a body or a file url comes from crons runs artifacts get, with the row's runId. The project and kind filters each take several values and keep an Artifact matching any of them.",
+    "pathParams": [
+        "workspaceId",
+        "cronId"
+    ],
+    "query": [
+        {
+            "name": "projectId",
+            "flag": "project",
+            "kind": "string",
+            "required": false,
+            "description": "Only the Artifacts of runs in these projects.",
+            "repeated": true
+        },
+        {
+            "name": "kind",
+            "flag": "kind",
+            "kind": "string",
+            "required": false,
+            "description": "Only the Artifacts of these kinds.",
+            "choices": [
+                "markdown",
+                "html",
+                "image",
+                "video"
+            ],
+            "repeated": true
+        },
+        {
+            "name": "page",
+            "flag": "page",
+            "kind": "integer",
+            "required": false,
+            "description": "1-based. Default 1."
+        },
+        {
+            "name": "pageSize",
+            "flag": "page-size",
+            "kind": "integer",
+            "required": false,
+            "description": "Default 25. Values above 100 are clamped, not rejected."
+        }
+    ],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/create.js

@@ -0,0 +1,65 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/organizations/{workspaceId}/crons",
+    "command": [
+        "crons",
+        "create"
+    ],
+    "summary": "Create a cron, enabled, with you as its creator, with zero or more of the workspace's projects: each fire is one Cron Run in its own sandbox, cloning only the selected repositories. Every run spends the workspace's Credentials, never a member's Subscription, so a workspace with no usable provider is refused. The model is an encoded id such as anthropic:opus__xhigh; null or left out uses the saved Workspace Default Model when its Provider has usable workspace Credentials, otherwise Kosuke's choice among usable workspace Credentials at run time. The crontab is read in the Workspace Timezone (workspaces timezone-set), and may not fire more often than every 15 minutes. A body that sends timezone is refused. From an agent (Sensei, a sandbox or a Cron Run) it is refused with 409 CRON_ALREADY_EXISTS when the workspace has a Cron by that name.",
+    "pathParams": [
+        "workspaceId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "name",
+                "flag": "name",
+                "kind": "string",
+                "required": true
+            },
+            {
+                "name": "projectIds",
+                "flag": "project",
+                "kind": "string",
+                "required": true,
+                "description": "The projects covered together by each Cron Run. Fixed when saved: a project created later joins only when the cron is edited to add it. Empty for a cron that needs no repository: its runs clone nothing.",
+                "repeated": true
+            },
+            {
+                "name": "prompt",
+                "flag": "prompt",
+                "kind": "string",
+                "required": true,
+                "description": "What each run asks the Cron Agent to do, handed to it word for word."
+            },
+            {
+                "name": "cronExpression",
+                "flag": "cron-expression",
+                "kind": "string",
+                "required": true,
+                "description": "Five fields: minute, hour, day of month, month, day of week, read in the Workspace Timezone (kosuke workspaces timezone-set). At most one fire every 15 minutes."
+            },
+            {
+                "name": "reportTo",
+                "flag": "report-to",
+                "kind": "string",
+                "required": false,
+                "description": "Reports to: the members, by the id `kosuke workspaces members` prints, whose Sensei each message from a run of this cron goes to, at most 10. With one, every message goes to them; with several, the run chooses among them. Empty, or left out on create, lets the run choose any member. Left out on update, it stays as saved; an empty list clears it.",
+                "repeated": true
+            },
+            {
+                "name": "model",
+                "flag": "model",
+                "kind": "string",
+                "required": false,
+                "description": "An encoded model id such as anthropic:opus__xhigh. Null, or left out on create, uses the Workspace Default Model at run time, then Kosuke's choice among available workspace Credentials."
+            }
+        ],
+        "required": true
+    },
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/delete.js

@@ -0,0 +1,18 @@
+export const operation = {
+    "method": "delete",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}",
+    "command": [
+        "crons",
+        "delete"
+    ],
+    "summary": "Delete a cron with its runs, their transcripts and their Artifacts. The sessions its runs filed stay. The creator or a workspace admin only.",
+    "pathParams": [
+        "workspaceId",
+        "cronId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false
+};

package/dist/generated/commands/crons/get.js

@@ -0,0 +1,19 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}",
+    "command": [
+        "crons",
+        "get"
+    ],
+    "summary": "Read one cron: its prompt, schedule, model, creator, when it runs next, its projects, its last run status, and how many runs in a row failed: five disable it.",
+    "pathParams": [
+        "workspaceId",
+        "cronId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/list.js

@@ -0,0 +1,54 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons",
+    "command": [
+        "crons",
+        "list"
+    ],
+    "summary": "List the workspace's crons, newest first, with each one's projects, creator and last run status: the status of its latest run.",
+    "pathParams": [
+        "workspaceId"
+    ],
+    "query": [
+        {
+            "name": "projectId",
+            "flag": "project",
+            "kind": "string",
+            "required": false,
+            "description": "Only the crons that include this project, alone or among others."
+        },
+        {
+            "name": "mine",
+            "flag": "mine",
+            "kind": "boolean",
+            "required": false,
+            "description": "Only the crons you created."
+        },
+        {
+            "name": "search",
+            "flag": "search",
+            "kind": "string",
+            "required": false,
+            "description": "Case-insensitive match on the name or the prompt."
+        },
+        {
+            "name": "page",
+            "flag": "page",
+            "kind": "integer",
+            "required": false,
+            "description": "1-based. Default 1."
+        },
+        {
+            "name": "pageSize",
+            "flag": "page-size",
+            "kind": "integer",
+            "required": false,
+            "description": "Default 25. Values above 100 are clamped, not rejected."
+        }
+    ],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/projects-resume.js

@@ -0,0 +1,21 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/projects/{projectId}/resume",
+    "command": [
+        "crons",
+        "projects",
+        "resume"
+    ],
+    "summary": "Projects are no longer paused one by one. Resume the cron. Returns 410 Gone.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "projectId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/run.js

@@ -0,0 +1,37 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/run",
+    "command": [
+        "crons",
+        "run"
+    ],
+    "summary": "Fire one Cron Run covering all the cron's projects or the selected projectIds, in its own sandbox; a cron with no projects runs with none. Refused for a cron stopped with No projects left until an edit picks a project. Answers with runs: [{ runId, status, projectIds, projectId }]; projectId is deprecated and names the first project by name, or null. The creator or a workspace admin only.",
+    "pathParams": [
+        "workspaceId",
+        "cronId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "projectIds",
+                "flag": "project",
+                "kind": "string",
+                "required": false,
+                "description": "Only these of the cron's projects. Left out, every project of the cron.",
+                "repeated": true
+            },
+            {
+                "name": "runId",
+                "flag": "run-id",
+                "kind": "string",
+                "required": false
+            }
+        ],
+        "required": false
+    },
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/runs-artifacts-get.js

@@ -0,0 +1,23 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/runs/{runId}/artifacts/{artifactId}",
+    "command": [
+        "crons",
+        "runs",
+        "artifacts",
+        "get"
+    ],
+    "summary": "Read one Artifact of a run of a cron, by its id or its slug: a markdown or html one carries its body, an image or a video a presigned url, its media type and its size.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "runId",
+        "artifactId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/runs-artifacts-list.js

@@ -0,0 +1,22 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/runs/{runId}/artifacts",
+    "command": [
+        "crons",
+        "runs",
+        "artifacts",
+        "list"
+    ],
+    "summary": "List the Artifacts a run of a cron published, most recently changed first. Rows only: a body or a file url comes from reading one.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "runId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/runs-cancel.js

@@ -0,0 +1,21 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/runs/{runId}/cancel",
+    "command": [
+        "crons",
+        "runs",
+        "cancel"
+    ],
+    "summary": "Stop a run of a cron that is still going, the way Stop on its page does. The run ends cancelled; the Artifacts it stored and the sessions it filed stay, and its sandbox is removed. The creator or a workspace admin only.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "runId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/crons/runs-diagnostics.js

@@ -0,0 +1,20 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/runs/{runId}/diagnostics",
+    "command": [
+        "crons",
+        "runs",
+        "diagnostics"
+    ],
+    "summary": "Read why a run of a cron ended as it did: its status, error, error code and stop source (member_stop, host_watch, deadline, replaced, sandbox_abort or runtime_error, with who stopped it), the sandbox it ran in and that sandbox's agent version, when each phase happened (queued, sandbox booted, credentials ready, agent requested, first event, done), the sandbox's own done payload, and the Cron Agent's log lines from the sandbox with secrets redacted. The log is capped at 256 KB and cleared after 30 days. The creator or a workspace admin only.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "runId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false
+};

package/dist/generated/commands/crons/runs-get.js

@@ -0,0 +1,21 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/crons/{cronId}/runs/{runId}",
+    "command": [
+        "crons",
+        "runs",
+        "get"
+    ],
+    "summary": "Read one run of a cron: the projects it covered, its status, the model it ran on, the Cron Agent's reply, and the sessions it filed with each one's status and whether it waits for an answer.",
+    "pathParams": [
+        "workspaceId",
+        "cronId",
+        "runId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};