@kosuke-ai/kosuke 0.0.0-stage → 1.0.1

package/dist/agent/summary.js

@@ -0,0 +1,419 @@
+import { providers } from '../generated/providers.js';
+import { readOverview } from '../integrations/api.js';
+import { createApiClient } from '../runtime/client.js';
+import { isTurnToken } from '../runtime/credentials.js';
+import { HttpError, NEEDS_YOU_FILTER, paginationTotal } from './http.js';
+/**
+ * `kosuke agent summary`: what needs the member, which providers and integrations
+ * are connected and what is New, in a few dozen lines an agent reads at the start of a
+ * conversation. Kept to about 1,500 tokens: each list is capped and names the
+ * command that reads the rest, and it claims only as many events as the other
+ * lines leave room for.
+ */
+const SUMMARY_TIMEOUT_MS = 8000;
+/**
+ * Shorter than the summary's own: a usage read asks the provider, and a slow provider
+ * must cost the digest its numbers, never the digest.
+ */
+const PROVIDERS_TIMEOUT_MS = 4000;
+/**
+ * Shorter still than the providers': connections are one cheap read, and a slow
+ * platform must cost the digest this section, never the digest.
+ */
+const INTEGRATIONS_TIMEOUT_MS = 3000;
+const NEEDS_YOU_SHOWN = 5;
+/** Connections listed before "and N more"; a member's own seven fit. */
+const INTEGRATIONS_SHOWN = 8;
+/** However much room is left: past this, the digest stops being a glance. */
+const EVENTS_SHOWN = 15;
+/**
+ * About 1,500 tokens, counted as characters at three a token: a URL's two
+ * UUIDs cost more tokens than words do, so a digest half links needs the margin.
+ */
+const BUDGET_CHARS = 4500;
+/** The Activity section's heading, its "and N more" line, and the line breaks around them. */
+const ACTIVITY_FRAME_CHARS = 150;
+// Caps on the words, never on the URL: a clipped URL opens nothing, and a
+// preview origin alone can take most of a line.
+const TITLE_MAX = 90;
+const TEXT_MAX = 140;
+const NAME_MAX = 40;
+/** `/projects/<uuid>/chat-sessions?session=<uuid>`, or a Backlog ticket's path, which is longer. */
+const SESSION_PATH_CHARS = 120;
+/** Room for an origin longer than any the digest has seen, such as a preview's. */
+const ORIGIN_CHARS_MIN = 64;
+// `satisfies`, so a query key the schema renames fails here, not at run time.
+const NEEDS_YOU_QUERY = {
+    ...NEEDS_YOU_FILTER,
+    limit: NEEDS_YOU_SHOWN,
+};
+const str = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+function rows(body) {
+    const list = body?.data;
+    return Array.isArray(list) ? list.filter((row) => row && typeof row === 'object') : [];
+}
+function where(row) {
+    const workspace = clip(str(row.workspaceName) ?? 'unnamed workspace', NAME_MAX);
+    const project = str(row.projectName);
+    return project ? `[${workspace}/${clip(project, NAME_MAX)}]` : `[${workspace}]`;
+}
+function clip(text, max) {
+    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)).trimEnd() + '…';
+}
+/**
+ * The longest an event line can be, so the digest claims only events it has
+ * room to print whole. Its session URL starts with the app's origin, which
+ * the digest knows only from the API's and the Needs You links.
+ */
+function eventLineMax(apiUrl, sessions) {
+    const origins = [apiUrl, ...sessions.map((row) => str(row.url))].flatMap((url) => {
+        try {
+            return url ? [new URL(url).origin.length] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    const url = Math.max(ORIGIN_CHARS_MIN, ...origins) + SESSION_PATH_CHARS;
+    return '- [/] '.length + 2 * NAME_MAX + TEXT_MAX + ', '.length + url;
+}
+/** `[workspace/project] title, reason, url`, one line per session. */
+function sessionLine(row) {
+    const title = clip(str(row.title) ?? 'Untitled session', TITLE_MAX);
+    const reason = str(row.needsYouReason) ?? 'needs you';
+    return [`- ${where(row)} ${title}`, reason, str(row.url)].filter(Boolean).join(', ');
+}
+/** `[workspace/project] text: subject, url`, the same words Settings → Activity shows. */
+function eventLine(event) {
+    const text = str(event.text) ?? str(event.kind) ?? 'Event';
+    const subject = str(event.subject);
+    const words = clip(`${text}${subject ? `: ${subject}` : ''}`, TEXT_MAX);
+    return [`- ${where(event)} ${words}`, str(event.sessionUrl)].filter(Boolean).join(', ');
+}
+const obj = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+/** The `data` of a success envelope, or null when the call failed or answered something else. */
+function dataOf(result) {
+    return result.response.ok ? obj(obj(result.data)?.data) : null;
+}
+/**
+ * A DeepSeek API key's balance, which it reports instead of windows: `balance 12.40 USD`,
+ * each currency apart, or `balance empty` once it cannot pay for a request.
+ */
+function balanceWords(usage) {
+    const balance = obj(usage?.balance);
+    if (!balance)
+        return null;
+    if (balance.available === false)
+        return 'balance empty';
+    const amounts = (Array.isArray(balance.amounts) ? balance.amounts : []).flatMap((amount) => {
+        const total = str(obj(amount)?.total);
+        const currency = str(obj(amount)?.currency);
+        return total && currency ? [`${total} ${currency}`] : [];
+    });
+    return amounts.length ? `balance ${amounts.join(', ')}` : null;
+}
+/** `session 42%, week 61%` or `session 42%, month 12%`, with only the windows the provider reported. */
+function usageWords(usage) {
+    const windows = ['session', 'week', 'month'].flatMap((name) => {
+        const utilization = obj(usage?.[name])?.utilization;
+        return typeof utilization === 'number' && Number.isFinite(utilization)
+            ? [`${name} ${Math.round(utilization)}% used`]
+            : [];
+    });
+    const balance = balanceWords(usage);
+    const words = balance ? [...windows, balance] : windows;
+    return words.length ? words.join(', ') : null;
+}
+const SUBSCRIPTIONS = {
+    anthropic: { label: 'Your Claude subscription', usage: 'claude_code' },
+    openai: { label: 'Your Codex subscription', usage: 'codex' },
+    zai: { label: 'Your GLM Coding Plan', usage: 'coding_plan' },
+    moonshot: { label: 'Your Kimi Code', usage: 'kimi_code' },
+    deepseek: { label: 'Your DeepSeek API key', usage: 'deepseek_api' },
+    meta: { label: 'Your Muse Code subscription', usage: 'muse_code' },
+    google: { label: 'Your Antigravity subscription', usage: 'antigravity' },
+};
+const AUTH_METHOD_NAMES = {
+    api_key: 'API key',
+    aws_bedrock: 'AWS Bedrock',
+    claude_code: 'Claude login',
+    codex: 'Codex login',
+    coding_plan: 'GLM Coding Plan',
+    kimi_code: 'Kimi Code',
+    deepseek_api: 'DeepSeek API',
+    muse_code: 'Muse Code',
+    antigravity: 'Antigravity',
+    gemini_api: 'Gemini API',
+};
+const WORKSPACE_USAGE = {
+    claude_code: '/api/organizations/{workspaceId}/ai-provider/claude-usage',
+    codex: '/api/organizations/{workspaceId}/ai-provider/codex-usage',
+    coding_plan: '/api/organizations/{workspaceId}/ai-provider/coding-plan-usage',
+    kimi_code: '/api/organizations/{workspaceId}/ai-provider/kimi-code-usage',
+    deepseek_api: '/api/organizations/{workspaceId}/ai-provider/deepseek-usage',
+    muse_code: '/api/organizations/{workspaceId}/ai-provider/muse-usage',
+    antigravity: '/api/organizations/{workspaceId}/ai-provider/google/usage',
+};
+function usagePlan(method) {
+    return Object.hasOwn(WORKSPACE_USAGE, method) ? method : null;
+}
+function subscriptionEntries(subscriptions) {
+    return providers.flatMap(({ key }) => {
+        const { label, usage } = SUBSCRIPTIONS[key];
+        if (key === 'google') {
+            const methods = obj(subscriptions.googleAccess)?.methods;
+            const signIn = Array.isArray(methods)
+                ? methods.map(obj).find((method) => method?.method === 'antigravity')
+                : null;
+            return signIn ? [{ label, needsReauth: signIn.needsReauth === true, usage }] : [];
+        }
+        const row = obj(subscriptions[key]);
+        if (!row || row.connected !== true)
+            return [];
+        return [{ label, needsReauth: row.needsReauth === true, usage }];
+    });
+}
+/** One entry per provider the workspace has an active, configured auth method for. */
+function workspaceEntries(settings) {
+    const configured = obj(settings.providers) ?? {};
+    return providers.flatMap(({ key, name }) => {
+        const provider = obj(configured[key]);
+        const method = str(provider?.activeAuthMethod);
+        const state = method ? obj(obj(provider?.authMethods)?.[method]) : null;
+        if (!method || !state || state.configured !== true)
+            return [];
+        return [
+            {
+                label: `Workspace ${name} (${AUTH_METHOD_NAMES[method] ?? method})`,
+                needsReauth: state.needsReauth === true,
+                usage: usagePlan(method),
+            },
+        ];
+    });
+}
+function providerLine(entry, usage) {
+    if (entry.needsReauth)
+        return `- ${entry.label}: needs reconnecting`;
+    return [`- ${entry.label}: connected`, usageWords(usage)].filter(Boolean).join(', ');
+}
+/**
+ * The Providers section's lines, or null when a connection read failed: half the
+ * connections would read as the other half not existing. A usage read that fails
+ * costs only that line's numbers.
+ */
+async function fetchProviders(client, workspace, signal) {
+    try {
+        const [subscriptions, settings] = await Promise.all([
+            client.GET('/api/user/subscriptions', { signal }).then(dataOf),
+            workspace
+                ? client
+                    .GET('/api/organizations/{workspaceId}/ai-provider', {
+                    params: { path: { workspaceId: workspace } },
+                    signal,
+                })
+                    .then(dataOf)
+                : null,
+        ]);
+        if (!subscriptions || (workspace && !settings))
+            return null;
+        const usage = (read) => read.then(dataOf).catch(() => null);
+        const mine = subscriptionEntries(subscriptions).map((entry) => ({
+            entry,
+            read: () => usage(client.GET('/api/user/subscriptions/usage', {
+                params: { query: { provider: entry.usage ?? 'claude_code' } },
+                signal,
+            })),
+        }));
+        const path = { workspaceId: workspace ?? '' };
+        const shared = (settings ? workspaceEntries(settings) : []).map((entry) => ({
+            entry,
+            read: () => usage(client.GET(WORKSPACE_USAGE[entry.usage ?? 'claude_code'], { params: { path }, signal })),
+        }));
+        const lines = await Promise.all([...mine, ...shared].map(async ({ entry, read }) => providerLine(entry, entry.usage && !entry.needsReauth ? await read() : null)));
+        return lines.length ? lines : ['- None connected.'];
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Integrations section's lines, one per connection: toolkit, alias, scope, label and the
+ * account it reaches. The platform decides which are the caller's (a member's personal ones come
+ * only where the credential may use them), so this lists what it was sent, each once. Null when
+ * there is no workspace to ask about; a refusal or a failed read still says so, because an
+ * absent section would read as "nothing is connected".
+ */
+async function fetchIntegrations(client, workspace, apiKey, signal) {
+    // A member's key names a workspace; a turn's token already is one.
+    if (!workspace && !isTurnToken(apiKey))
+        return null;
+    try {
+        const result = await readOverview(client, workspace ? { workspace } : {}, signal);
+        if (!result.ok) {
+            return [
+                result.status === 403
+                    ? '- Not available to this credential.'
+                    : '- Could not be read. `kosuke integrations list` retries.',
+            ];
+        }
+        const seen = new Set();
+        const lines = [];
+        for (const toolkit of result.overview.toolkits) {
+            for (const connection of toolkit.connections) {
+                if (seen.has(connection.id))
+                    continue;
+                seen.add(connection.id);
+                lines.push(integrationLine(toolkit.toolkit, connection));
+            }
+        }
+        if (lines.length === 0)
+            return ['- None connected.'];
+        const total = Math.max(result.overview.connectionTotal, lines.length);
+        const shown = lines.slice(0, INTEGRATIONS_SHOWN);
+        if (total > shown.length) {
+            const scope = workspace ? ` --workspace ${workspace}` : '';
+            shown.push(`(and ${total - shown.length} more: kosuke integrations list${scope})`);
+        }
+        return shown;
+    }
+    catch {
+        return null;
+    }
+}
+function integrationLine(toolkit, connection) {
+    const label = clip(connection.label, NAME_MAX);
+    const identity = clip(connection.accountIdentity ?? 'account unknown', NAME_MAX);
+    return `- ${clip(toolkit, NAME_MAX)}: ${connection.alias}, ${connection.scope}, "${label}", ${identity}`;
+}
+/** Never clipped: a workspace missing here would read as one the digest did not cover. */
+function coverageLine(sessions) {
+    const covered = sessions?.meta?.workspaces;
+    const names = Array.isArray(covered)
+        ? covered.map((workspace) => str(workspace?.name)).filter((name) => name !== null)
+        : [];
+    return `Workspaces covered: ${names.length ? names.join(', ') : 'none'}.`;
+}
+export function planSummary(options) {
+    const { sessions, apiUrl, now, workspace, peek = false } = options;
+    const scope = workspace ? ` --workspace ${workspace}` : '';
+    const stamp = new Date(now).toISOString().slice(0, 16).replace('T', ' ') + ' UTC';
+    const head = [`Kosuke summary, ${stamp}, ${apiUrl}`, ''];
+    const needing = rows(sessions);
+    const needTotal = paginationTotal(sessions) ?? needing.length;
+    if (needTotal === 0) {
+        head.push('No session needs you.');
+    }
+    else {
+        head.push(`${needTotal} session${needTotal === 1 ? ' needs' : 's need'} you:`);
+        const shown = needing.slice(0, NEEDS_YOU_SHOWN);
+        head.push(...shown.map(sessionLine));
+        if (needTotal > shown.length) {
+            head.push(`(and ${needTotal - shown.length} more: kosuke sessions all --needs-you --owners me${scope})`);
+        }
+    }
+    head.push('');
+    if (options.providers?.length)
+        head.push('Providers:', ...options.providers, '');
+    if (options.integrations?.length) {
+        head.push('Integrations (`kosuke integrations list` shows their tools):', ...options.integrations, '');
+    }
+    const coverage = coverageLine(sessions);
+    const room = BUDGET_CHARS - head.join('\n').length - coverage.length - ACTIVITY_FRAME_CHARS - scope.length;
+    const lineMax = eventLineMax(apiUrl, needing);
+    const claim = Math.max(0, Math.min(EVENTS_SHOWN, Math.floor(room / (lineMax + 1))));
+    return {
+        head,
+        coverage,
+        claim,
+        peek,
+        activityQuery: {
+            ...(claim > 0 && !peek ? { markSeen: true } : { unseen: true }),
+            limit: Math.max(claim, 1),
+            ...(workspace ? { workspace } : {}),
+        },
+        scope,
+    };
+}
+/** The whole digest, once `activity` answered the plan's `activityQuery`. */
+export function renderSummary(plan, activity) {
+    const lines = [...plan.head];
+    // Every event the read returned is printed: without a peek, each is already marked seen.
+    const events = plan.claim > 0 ? rows(activity) : [];
+    const rest = (paginationTotal(activity) ?? events.length) - events.length;
+    const noun = (count) => (count === 1 ? 'event' : 'events');
+    if (events.length) {
+        const state = plan.peek ? 'still New' : 'now marked seen';
+        lines.push(`${events.length} New ${noun(events.length)}, oldest first, ${state}:`);
+        lines.push(...events.map(eventLine));
+        if (rest > 0) {
+            lines.push(`(and ${rest} more New ${noun(rest)}, still New: kosuke activity list --unseen${plan.scope})`);
+        }
+    }
+    else if (rest > 0) {
+        lines.push(`${rest} New ${noun(rest)}, not listed here and still New: kosuke activity list --unseen${plan.scope}`);
+    }
+    else {
+        lines.push('No new activity.');
+    }
+    lines.push('', plan.coverage);
+    return lines.join('\n');
+}
+/**
+ * The whole digest, or one line saying why not, so the agent reading it
+ * knows to query the CLI itself. Needs You, the providers and the integrations are read first:
+ * their lines decide how many events fit, and the Activity read marks events
+ * seen, so a digest that failed after it would lose them.
+ */
+export async function fetchSummary(options) {
+    if (!options.apiKey)
+        return unavailable('not logged in', 'kosuke auth login');
+    const client = createApiClient({
+        apiUrl: options.apiUrl,
+        apiKey: options.apiKey,
+        fetch: options.fetch,
+    });
+    const signal = AbortSignal.timeout(options.timeoutMs ?? SUMMARY_TIMEOUT_MS);
+    try {
+        const workspace = options.workspace ? { workspace: options.workspace } : {};
+        const [needsYou, providers, integrations] = await Promise.all([
+            client.GET('/api/chat-sessions', {
+                params: { query: { ...NEEDS_YOU_QUERY, ...workspace } },
+                signal,
+            }),
+            fetchProviders(client, options.workspace, AbortSignal.any([signal, AbortSignal.timeout(PROVIDERS_TIMEOUT_MS)])),
+            fetchIntegrations(client, options.workspace, options.apiKey, AbortSignal.any([signal, AbortSignal.timeout(INTEGRATIONS_TIMEOUT_MS)])),
+        ]);
+        const sessions = body(needsYou);
+        const plan = planSummary({
+            sessions,
+            providers,
+            integrations,
+            apiUrl: options.apiUrl,
+            now: (options.now ?? Date.now)(),
+            ...workspace,
+            peek: options.peek ?? false,
+        });
+        const activity = body(await client.GET('/api/activity', { params: { query: plan.activityQuery }, signal }));
+        return renderSummary(plan, activity);
+    }
+    catch (error) {
+        return unavailable(reasonOf(error), 'kosuke auth status');
+    }
+}
+function body(result) {
+    if (!result.response.ok)
+        throw new HttpError(result.response.status);
+    return result.data;
+}
+function reasonOf(error) {
+    if (error instanceof HttpError) {
+        return error.status === 401 ? 'the API key was refused (HTTP 401)' : `HTTP ${error.status}`;
+    }
+    const name = error instanceof Error ? error.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError')
+        return 'the platform did not answer in time';
+    return 'the platform could not be reached';
+}
+function unavailable(reason, next) {
+    return `Kosuke summary unavailable: ${reason}. Run ${next}.`;
+}

package/dist/commands/agent.js

@@ -0,0 +1,22 @@
+import { fetchSummary } from '../agent/summary.js';
+export function attachAgentCommands(root, runtime, deps = {}) {
+    const { fetch, now, stdout = (line) => process.stdout.write(line + '\n') } = deps;
+    const agent = root.command('agent').description('What an agent reads about your Kosuke.');
+    agent
+        .command('summary')
+        .description('Print what needs you and your oldest New Activity as a short digest for an agent to read. ' +
+        'Marks seen only the events it prints, and none with --peek; the rest stay New.')
+        .option('--workspace <id>', 'Only this workspace.')
+        .option('--peek', 'Print the events without marking them seen.')
+        .action(async (options) => {
+        const { apiKey, apiUrl } = runtime.credentials();
+        stdout(await fetchSummary({
+            apiUrl,
+            apiKey,
+            ...(options.workspace ? { workspace: options.workspace } : {}),
+            ...(options.peek ? { peek: true } : {}),
+            ...(fetch ? { fetch } : {}),
+            ...(now ? { now } : {}),
+        }));
+    });
+}

package/dist/commands/auth.js

@@ -0,0 +1,117 @@
+import { createApiClient } from '../runtime/client.js';
+import { credentialsPath, DEFAULT_API_URL, deleteCredentials, writeCredentials, } from '../runtime/config.js';
+export function attachAuthCommands(root, runtime, deps = {}) {
+    const { env = process.env, fetch, prompt = promptHidden, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+        process.exitCode = code;
+    }, } = deps;
+    const auth = root.command('auth').description('Manage the API key this machine uses.');
+    auth
+        .command('login')
+        .description('Store an API key, after checking it works. Takes the global --api-key when ' +
+        'given, and prompts otherwise. Create one in Settings.')
+        .action(async () => {
+        // The global --api-key is the one flag: commander reads a program option
+        // wherever it appears, so a second `--api-key` on this subcommand would
+        // never receive the value. Only that flag counts as the key to store:
+        // logging in is an explicit act, and a stale KOSUKE_API_KEY left in the
+        // shell is exactly what someone running this may be trying to replace.
+        const resolved = runtime.credentials();
+        const apiUrl = resolved.apiUrl;
+        const apiKey = resolved.apiKeySource === 'flag' ? resolved.apiKey : (await prompt('API key: ')).trim();
+        if (!apiKey) {
+            stderr('No API key given.');
+            exit(1);
+            return;
+        }
+        const who = await verify(apiUrl, apiKey, fetch);
+        if (!who.ok) {
+            stderr(`The API key was refused by ${apiUrl} (HTTP ${who.status}). Nothing saved.`);
+            exit(1);
+            return;
+        }
+        const path = writeCredentials({ apiKey, ...(apiUrl !== DEFAULT_API_URL ? { apiUrl } : {}) }, env);
+        stdout(`Logged in to ${apiUrl}; member of ${who.workspaces} workspace${who.workspaces === 1 ? '' : 's'}. API key saved to ${path}.`);
+    });
+    auth
+        .command('status')
+        .description('Show where the API key comes from and whether the platform accepts it.')
+        .action(async () => {
+        const { apiKey, apiKeySource, apiUrl, apiUrlSource } = runtime.credentials();
+        const result = {
+            apiUrl,
+            apiUrlSource,
+            apiKeySource,
+            credentialsFile: credentialsPath(env),
+        };
+        if (apiKey) {
+            const who = await verify(apiUrl, apiKey, fetch);
+            result.tokenPrefix = apiKey.slice(0, 12);
+            result.accepted = who.ok;
+            if (who.ok)
+                result.workspaces = who.workspaces;
+            else
+                result.status = who.status;
+        }
+        else {
+            result.accepted = false;
+        }
+        stdout(JSON.stringify(result, null, 2));
+        if (!result.accepted)
+            exit(1);
+    });
+    auth
+        .command('logout')
+        .description('Delete the stored API key. A key from the environment or a flag is untouched.')
+        .action(() => {
+        const path = credentialsPath(env);
+        stdout(deleteCredentials(env) ? `Removed ${path}.` : `Nothing stored at ${path}.`);
+    });
+}
+/** The cheapest call a key must be able to make: the workspaces it belongs to. */
+async function verify(apiUrl, apiKey, fetch) {
+    const client = createApiClient({ apiUrl, apiKey, fetch });
+    const { data, response } = await client.GET('/api/organizations');
+    if (!response.ok)
+        return { ok: false, status: response.status };
+    const list = data?.data;
+    return { ok: true, workspaces: Array.isArray(list) ? list.length : 0 };
+}
+/** Read a line without echoing it, when stdin is a terminal. */
+async function promptHidden(question) {
+    const { stdin, stdout } = process;
+    stdout.write(question);
+    if (!stdin.isTTY) {
+        const { createInterface } = await import('node:readline/promises');
+        const rl = createInterface({ input: stdin, terminal: false });
+        const answer = await rl.question('');
+        rl.close();
+        return answer;
+    }
+    return new Promise((resolve) => {
+        let answer = '';
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === '\n' || char === '\r' || char === '\u0004') {
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    stdin.off('data', onData);
+                    stdout.write('\n');
+                    resolve(answer);
+                    return;
+                }
+                if (char === '\u0003') {
+                    stdin.setRawMode(false);
+                    process.exit(130);
+                }
+                if (char === '\u007f' || char === '\b')
+                    answer = answer.slice(0, -1);
+                else
+                    answer += char;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}