@kosuke-ai/kosuke 0.0.0-stage → 1.0.1

package/dist/generated/commands/workspaces/skills-update.js

@@ -0,0 +1,36 @@
+export const operation = {
+    "method": "patch",
+    "path": "/api/organizations/{workspaceId}/skills/{skillId}",
+    "command": [
+        "workspaces",
+        "skills",
+        "update"
+    ],
+    "summary": "Enable or disable a custom skill, or replace every file it holds; at least one of enabled and files. Admins only. Answers 204.",
+    "pathParams": [
+        "workspaceId",
+        "skillId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "files",
+                "flag": "files",
+                "kind": "json",
+                "required": false
+            },
+            {
+                "name": "enabled",
+                "flag": "enabled",
+                "kind": "boolean",
+                "required": false
+            }
+        ],
+        "required": true
+    },
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/workspaces/stop-sandboxes.js

@@ -0,0 +1,28 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/organizations/{workspaceId}/stop-sandboxes",
+    "command": [
+        "workspaces",
+        "stop-sandboxes"
+    ],
+    "summary": "Pause the sandboxes of the given chat sessions.",
+    "pathParams": [
+        "workspaceId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "sessionIds",
+                "flag": "session-ids",
+                "kind": "json",
+                "required": true
+            }
+        ],
+        "required": true
+    },
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/workspaces/timezone-set.js

@@ -0,0 +1,29 @@
+export const operation = {
+    "method": "put",
+    "path": "/api/organizations/{workspaceId}/timezone",
+    "command": [
+        "workspaces",
+        "timezone-set"
+    ],
+    "summary": "Set the Workspace Timezone, the IANA zone every cron of the workspace is read and shown in, e.g. Europe/Rome. Each enabled cron's next run moves to the new zone, except one already due, which fires on its slot. Refused, naming the crons, when any cron would fire more often than every 15 minutes or never in the new zone; nothing changes then. Sending the zone already set changes nothing. Owners and admins only.",
+    "pathParams": [
+        "workspaceId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "timezone",
+                "flag": "timezone",
+                "kind": "string",
+                "required": true,
+                "description": "The IANA zone every cron of the workspace is read and shown in, e.g. Europe/Rome or UTC."
+            }
+        ],
+        "required": true
+    },
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/commands/workspaces/usage.js

@@ -0,0 +1,33 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/organizations/{workspaceId}/usage",
+    "command": [
+        "workspaces",
+        "usage"
+    ],
+    "summary": "Read sandbox usage by day and by project. start must precede end and the range is capped at 366 days.",
+    "pathParams": [
+        "workspaceId"
+    ],
+    "query": [
+        {
+            "name": "start",
+            "flag": "start",
+            "kind": "string",
+            "required": false,
+            "description": "Range start, any Date-parsable string. Default: end minus 30 days."
+        },
+        {
+            "name": "end",
+            "flag": "end",
+            "kind": "string",
+            "required": false,
+            "description": "Range end, any Date-parsable string. Default: now."
+        }
+    ],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false,
+    "agents": "all"
+};

package/dist/generated/providers.js

@@ -0,0 +1,31 @@
+// Generated from the sandbox CLI model catalog by scripts/generate.ts. Do not edit.
+export const providers = [
+    {
+        "key": "anthropic",
+        "name": "Anthropic"
+    },
+    {
+        "key": "openai",
+        "name": "OpenAI"
+    },
+    {
+        "key": "zai",
+        "name": "Z.ai"
+    },
+    {
+        "key": "moonshot",
+        "name": "Moonshot AI"
+    },
+    {
+        "key": "deepseek",
+        "name": "DeepSeek"
+    },
+    {
+        "key": "meta",
+        "name": "Meta"
+    },
+    {
+        "key": "google",
+        "name": "Google"
+    }
+];

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from './program.js';
+run(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`kosuke: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/integrations/api.js

@@ -0,0 +1,136 @@
+import { ResponseTooLarge } from '../runtime/client.js';
+/**
+ * The integration tools routes, read the way a command prints them. Everything
+ * the platform sends is text from a connected third party or a user's label, so
+ * it is flattened to bounded one-liners here and never interpreted.
+ */
+export const TOOLS_PATH = '/api/agent-integrations/tools';
+const UNAVAILABLE = 'Integration tools are temporarily unavailable.';
+const TOO_LARGE = 'The platform answer was too large to read. Narrow the request.';
+const TIMED_OUT = 'The platform did not answer in time.';
+/** A write may have landed before the connection failed; a retry could repeat it. */
+const UNKNOWN_OUTCOME = 'The integration tool call did not complete and its outcome is unknown. Do not retry it; read the current state first.';
+export const isRow = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const rowsOf = (value) => (Array.isArray(value) ? value.filter(isRow) : []);
+/** One bounded line: control characters and runs of space become one space. */
+export function oneLine(value, max) {
+    if (typeof value !== 'string')
+        return '';
+    const flat = value.replace(/[\p{Cc}\p{Cf}\s]+/gu, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+const count = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : 0;
+export function connectionOf(row) {
+    const id = oneLine(row.id, 16);
+    const alias = oneLine(row.alias, 80);
+    if (!alias)
+        return null;
+    return {
+        id,
+        alias,
+        scope: row.scope === 'personal' ? 'personal' : 'workspace',
+        label: oneLine(row.label, 60),
+        accountIdentity: oneLine(row.accountIdentity, 80) || null,
+    };
+}
+/** `data` of a `view=overview` answer, or null for any other shape (an older platform's). */
+function parseOverview(data) {
+    if (!isRow(data) || data.view !== 'overview' || !Array.isArray(data.toolkits))
+        return null;
+    const toolkits = rowsOf(data.toolkits).map((row) => {
+        const tools = isRow(row.tools) ? row.tools : {};
+        const toolkit = oneLine(row.toolkit, 64);
+        return {
+            toolkit,
+            name: oneLine(row.name, 60) || toolkit,
+            browser: row.kind === 'browser',
+            connections: rowsOf(row.connections).flatMap((connection) => connectionOf(connection) ?? []),
+            read: count(tools.read),
+            write: count(tools.write),
+        };
+    });
+    const tools = Array.isArray(data.tools)
+        ? rowsOf(data.tools).map((row) => ({
+            name: oneLine(row.name, 80),
+            toolkit: oneLine(row.toolkit, 64),
+            access: row.access === 'read' ? 'read' : 'write',
+            description: oneLine(row.description, 160),
+            aliases: (Array.isArray(row.aliases) ? row.aliases : [])
+                .map((alias) => oneLine(alias, 80))
+                .filter(Boolean),
+        }))
+        : null;
+    return {
+        toolkits,
+        connectionTotal: count(data.connectionTotal),
+        tools,
+        toolTotal: tools ? count(data.toolTotal) : null,
+        note: oneLine(data.note, 400) || null,
+    };
+}
+/** The platform's own sentence for a refusal, bounded; its status when it said nothing. */
+function sentenceOf(error, status) {
+    const said = isRow(error) ? oneLine(error.error, 300) : '';
+    return said || `HTTP ${status}`;
+}
+/**
+ * Why a request failed, in words the reader can act on. The 4xx sentences are
+ * the platform's own (a Connector Token, a workspace the key is not a member of,
+ * an agent); only 401 and 429 are worded here.
+ */
+export function failureOf(status, error, method) {
+    // A gateway answering for the app does not prove the app never ran the write.
+    if (method === 'POST' && (status === 502 || status === 504)) {
+        return { ok: false, status, message: UNKNOWN_OUTCOME };
+    }
+    if (status === 401) {
+        return {
+            ok: false,
+            status,
+            message: 'The API key was refused (HTTP 401). Run `kosuke auth status`.',
+        };
+    }
+    if (status === 429) {
+        return { ok: false, status, message: 'Too many requests. Try again shortly.' };
+    }
+    if (status >= 400 && status < 500) {
+        return { ok: false, status, message: sentenceOf(error, status) };
+    }
+    return { ok: false, status, message: UNAVAILABLE };
+}
+/** A request that never got an answer. */
+export function transportFailure(error, method) {
+    const name = error instanceof Error ? error.name : '';
+    if (method === 'GET' && error instanceof ResponseTooLarge) {
+        return { ok: false, status: null, message: TOO_LARGE };
+    }
+    const timedOut = name === 'TimeoutError' || name === 'AbortError';
+    if (method === 'POST')
+        return { ok: false, status: null, message: UNKNOWN_OUTCOME };
+    return { ok: false, status: null, message: timedOut ? TIMED_OUT : UNAVAILABLE };
+}
+/** The overview view: the connections per toolkit, and the matching tools once a filter is set. */
+export async function readOverview(client, query, signal) {
+    const params = { view: 'overview', ...query };
+    try {
+        const { data, error, response } = await client.GET(TOOLS_PATH, {
+            params: { query: params },
+            signal,
+        });
+        if (!response.ok)
+            return failureOf(response.status, error, 'GET');
+        const raw = isRow(data) ? data.data : undefined;
+        const overview = parseOverview(raw);
+        if (!overview) {
+            return {
+                ok: false,
+                status: response.status,
+                message: 'This platform does not offer the integrations overview yet.',
+            };
+        }
+        return { ok: true, overview, raw };
+    }
+    catch (error) {
+        return transportFailure(error, 'GET');
+    }
+}

package/dist/integrations/render.js

@@ -0,0 +1,59 @@
+/**
+ * `kosuke integrations list` as text: a block per toolkit, with its connections
+ * and tool counts, then the matching tools when a filter is set. A cut is never
+ * silent: the server's note is printed whenever it sent one.
+ */
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+function connectionLine(connection) {
+    const identity = connection.accountIdentity ?? 'account unknown';
+    const id = connection.id ? `, id ${connection.id}` : '';
+    return `${connection.alias}: ${connection.scope}, "${connection.label}", ${identity}${id}`;
+}
+function toolLine(tool, width) {
+    const access = (tool.access === 'read' ? '[read-only]' : '[writes]').padEnd(11);
+    const accounts = tool.aliases.length > 0 ? `  [account: ${tool.aliases.join(', ')}]` : '';
+    return `${tool.name.padEnd(width)}  ${access}  ${tool.description}${accounts}`.trimEnd();
+}
+export function renderOverview(overview, filtered) {
+    const { toolkits, tools, note } = overview;
+    if (toolkits.length === 0 && overview.connectionTotal === 0) {
+        return filtered ? 'No connected tool matches.\n' : 'No integrations are connected.\n';
+    }
+    // A browser site has connections and no tools, so a filter naming it still shows them.
+    const connected = toolkits.some((toolkit) => toolkit.browser && toolkit.connections.length > 0);
+    if (filtered && tools?.length === 0 && !connected)
+        return 'No connected tool matches.\n';
+    const width = Math.max(0, ...(tools ?? []).map((tool) => tool.name.length));
+    const blocks = toolkits.map((toolkit) => {
+        const offer = toolkit.browser
+            ? 'browser, no tools'
+            : `${toolkit.read} read, ${toolkit.write} write tools`;
+        const lines = [
+            `${toolkit.name} (${toolkit.toolkit}): ${offer}`,
+            ...toolkit.connections.map((connection) => `  ${connectionLine(connection)}`),
+        ];
+        const own = (tools ?? []).filter((tool) => tool.toolkit === toolkit.toolkit);
+        if (own.length > 0) {
+            lines.push('  tools:', ...own.map((tool) => `    ${toolLine(tool, width)}`));
+        }
+        return lines.join('\n');
+    });
+    const out = [blocks.join('\n\n')];
+    if (tools) {
+        if (tools.length > 0) {
+            out.push(`${tools.length} of ${plural(overview.toolTotal ?? tools.length, 'tool')} shown.`);
+        }
+    }
+    else {
+        out.push(`${plural(overview.connectionTotal, 'connection')}. ` +
+            "`kosuke integrations list --toolkit <slug>` shows a toolkit's tools; " +
+            "`kosuke integrations describe <tool>` prints one tool's input schema.");
+    }
+    if (note)
+        out.push(note);
+    return `${out.join('\n\n')}\n`;
+}
+/** One connection per line, for a refusal that asks the caller to pick one. */
+export function choiceLines(choices) {
+    return choices.map((choice) => `  ${connectionLine(choice)}`).join('\n');
+}

package/dist/program.js

@@ -0,0 +1,73 @@
+import { Command } from 'commander';
+import { attachSkillMarkerCommands, runSkillMarkerCommand } from './commands/skill-runs.js';
+import { attachAgentCommands } from './commands/agent.js';
+import { attachAuthCommands } from './commands/auth.js';
+import { attachIntegrationsCommands } from './commands/integrations.js';
+import { attachWatchCommand } from './commands/watch.js';
+import { operations } from './generated/commands/index.js';
+import { attachOperation } from './runtime/attach.js';
+import { agentTokenOf, isReachable } from './runtime/agent-tokens.js';
+import { createRuntime, ExitSignal } from './runtime/runtime.js';
+import { version } from './runtime/version.js';
+/**
+ * The command tree: `auth`, `agent`, `integrations list|describe|call` and `sessions watch` by
+ * hand, everything else from the generated descriptors. Global flags are read
+ * before any subcommand runs, so the runtime the subcommands share is built once, from them.
+ */
+export function createProgram(options = {}) {
+    const program = new Command('kosuke')
+        .description('Drive the Kosuke platform from your own machine.')
+        .version(version)
+        .option('--api-key <key>', 'API key; overrides KOSUKE_API_KEY and the stored one.')
+        .option('--api-url <url>', 'Platform URL; overrides KOSUKE_API_URL. Default https://app.kosuke.ai.')
+        // commander's default is kept: a program option is read wherever it
+        // appears, so `kosuke projects list --api-key X` works as the README shows.
+        .showHelpAfterError('(add --help for usage)')
+        .configureHelp({ sortSubcommands: true });
+    // Built lazily, on the first use, so `--help` and `--version` never touch
+    // the credentials file.
+    let runtime = null;
+    const runtimeFor = () => (runtime ??= (options.runtime ?? ((flags) => createRuntime({ ...options.process, flags })))(program.opts()));
+    const lazy = {
+        credentials: () => runtimeFor().credentials(),
+        client: (o) => runtimeFor().client(o),
+        output: (outcome) => runtimeFor().output(outcome),
+    };
+    attachAuthCommands(program, lazy, options.auth);
+    // An agent's credential reaches what its member's API key does, less the
+    // deletes and the personal credentials, so the tree shows that and
+    // `kosuke --help` there is true rather than a list of 403s.
+    // Read from the env alone, which keeps `--help` off the credentials file.
+    const token = (options.process?.env ?? process.env).KOSUKE_API_KEY;
+    const narrowedTo = agentTokenOf(token);
+    const reachable = narrowedTo
+        ? operations.filter((operation) => isReachable(operation.agents, narrowedTo))
+        : operations;
+    for (const operation of reachable)
+        attachOperation(program, operation, lazy);
+    // Every agent token reads the digest's two lists as its member. Only a
+    // member's own key and their Sensei may mark Activity seen, so the others
+    // read it with `--peek`.
+    attachAgentCommands(program, lazy, options.agent);
+    if (narrowedTo === null || narrowedTo === 'sandboxToken')
+        attachSkillMarkerCommands(program, options.process);
+    // Beside the generated `integrations tools` and `execute`, which stay raw passthroughs.
+    attachIntegrationsCommands(program, lazy, options.integrations);
+    // The job stream admits a member's API key only; it closes 4401 on every narrower token.
+    if (narrowedTo === null)
+        attachWatchCommand(program, lazy, options.watch);
+    return program;
+}
+/** Run to completion; an ExitSignal has already reported and set the exit code. */
+export async function run(argv, options) {
+    try {
+        if (await runSkillMarkerCommand(argv.slice(2), options?.process))
+            return;
+        await createProgram(options).parseAsync([...argv]);
+    }
+    catch (error) {
+        if (error instanceof ExitSignal)
+            return;
+        throw error;
+    }
+}

package/dist/runtime/agent-tokens.js

@@ -0,0 +1,39 @@
+/**
+ * The agent tokens the tree narrows to, and the one place that maps each to the
+ * key prefixes it is minted with and the document extension that marks the
+ * operations it reaches. The server enforces what a token reaches; here it only
+ * decides which commands the tree shows.
+ *
+ * Imports nothing, so the generator can load it on plain node.
+ */
+export const AGENT_TOKENS = [
+    // Wire contract with `src/lib/auth/sandbox-agent-token.ts`: a chat sandbox's own Turn.
+    { token: 'sandboxToken', prefixes: ['kosuke_sbx_'], extension: 'x-kosuke-sandbox-token' },
+    // Wire contract with `src/lib/auth/cron-token.ts`: one Cron Run.
+    { token: 'cronToken', prefixes: ['kosuke_crn_'], extension: 'x-kosuke-cron-token' },
+    // Wire contract with `src/lib/auth/sensei-token.ts`: a Sensei Chat's Turn. A token minted
+    // before the Sensei rename carries `kosuke_lead_` until it expires; drop that prefix one
+    // release after the rename.
+    {
+        token: 'senseiToken',
+        prefixes: ['kosuke_sensei_', 'kosuke_lead_'],
+        extension: 'x-kosuke-sensei-token',
+    },
+];
+/** The agent token a key is, by its prefix; null for a member's own key or none. */
+export function agentTokenOf(key) {
+    if (!key)
+        return null;
+    const found = AGENT_TOKENS.find(({ prefixes }) => prefixes.some((prefix) => key.startsWith(prefix)));
+    return found?.token ?? null;
+}
+/** The descriptor value for the agent tokens the document grants an operation. */
+export function agentReach(granted) {
+    const tokens = AGENT_TOKENS.map(({ token }) => token).filter((token) => granted.includes(token));
+    if (tokens.length === 0)
+        return undefined;
+    return tokens.length === AGENT_TOKENS.length ? 'all' : tokens;
+}
+export function isReachable(reach, token) {
+    return reach === 'all' || (reach?.includes(token) ?? false);
+}