@quadient/skillshare 1.8.0 → 1.9.0

package/README.md

@@ -19,6 +19,35 @@ bun run index.ts install 12 0.1.0 --target ./installed
 bun run index.ts install --skill-version-id 42 --target ./installed
 ```
 
+## Connected agents
+
+`skillshare agents listen` lets Skillshare run Claude Code (`claude`) or Codex (`codex`) tasks
+on this computer. The listener reports the installed agents with their models and reasoning
+levels. Choose which computer and configuration runs each kind of task under **Connected
+agents** in Skillshare. Agents run with your full local permissions and configuration,
+without permission prompts.
+
+```sh
+skillshare agents status
+skillshare agents listen --workdir ~/Research
+skillshare agents listen --name desktop --max-concurrency 2
+```
+
+`--sandbox` keeps every agent read-only. Claude Code may only read files, search the web
+and use the Skillshare MCP; Codex runs in its read-only sandbox. A profile can do the same
+with `"sandbox": true`.
+
+Optional named profiles in `~/.config/skillshare/agents.json` set a working directory and
+extra arguments. Only the name, agent, model, reasoning and the working directory's last
+segment are sent to Skillshare.
+
+```json
+{ "profiles": [
+  { "name": "piq-opus-high", "agent": "claude", "model": "opus", "reasoning": "high",
+    "workdir": "~/Research/piq-modules", "args": ["--add-dir", "~/Research/piq-projects"] }
+] }
+```
+
 ## Teams MCP
 
 Starting with 1.7.0, `skillshare teams login` opens a dedicated local browser profile,
@@ -41,6 +70,10 @@ skillshare teams access readOnly
 skillshare teams logout
 ```
 
+Starting with 1.8.1, Teams uses the Microsoft account object id that Skillshare records at
+web sign-in, not the Skillshare user id. If the server does not know it yet, `teams login`
+opens one more Skillshare sign-in in the browser to link the account.
+
 Use `teams login local` for localhost or `--server <https-origin>` for another host.
 `login` accepts `--server` too. Browser options: `--browser chrome|msedge|chromium`,
 `--headless`, and `--browser-profile <dedicated-profile-directory>`.
@@ -50,6 +83,13 @@ permissions, Microsoft session lifetime and file-tool differences in the hosted
 
 ## Behavior
 
+Starting with 1.9.0:
+
+- `agents listen` and `agents status` run Claude Code and Codex tasks from Skillshare on this computer (see [Connected agents](#connected-agents)); `--sandbox` keeps them read-only.
+- Commands print readable text. Scripts that parsed JSON from `whoami`, `list`, `show`, `upload`, `pages list|show|runtime|upload` or `teams status|test|upload` must add `--json`; with `--json` progress goes to stderr and stdout contains only JSON.
+- `show` accepts a skill name as well as an id.
+- `pages upload` refuses build output folder names such as `dist` or `build` without `--slug`, says whether it creates or replaces a page, refuses pages owned by someone else unless you are an admin, and prints the page URL.
+
 Starting with 1.8.0:
 
 - `install` and `update` download into a staging directory first, so a failed transfer leaves the existing install untouched. Files that a new version no longer contains are removed.
@@ -209,7 +249,7 @@ npx @quadient/skillshare update 12 --target ./installed
 
 Publish an authenticated static page. The upload replaces the page's complete
 content, and the directory must contain `index.html` at its root. By default the
-directory name is used as the page slug:
+directory name is used as the page slug; build output folders such as `dist` need `--slug`:
 
 ```bash
 npx @quadient/skillshare pages upload ./release-notes

package/dist/agents-detect.js

@@ -0,0 +1,147 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+/** Model aliases Claude Code resolves to the latest release; Claude Code itself has no command that lists models. */
+export const CLAUDE_MODELS = ['fable', 'opus', 'sonnet', 'haiku'];
+export const CLAUDE_EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$/;
+export function profilesPath(home = homedir()) {
+    return process.platform === 'win32'
+        ? join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'skillshare', 'agents.json')
+        : join(home, '.config', 'skillshare', 'agents.json');
+}
+export async function detectAgents(options = {}) {
+    const home = options.home ?? homedir();
+    const env = options.env ?? process.env;
+    const version = options.version ?? commandVersion;
+    const read = options.read ?? readOptional;
+    const agents = [];
+    const problems = [];
+    const claudeVersion = await version('claude');
+    if (claudeVersion !== null) {
+        const settings = parseJson(await read(join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), 'settings.json')));
+        const configured = Array.isArray(settings?.availableModels) ? settings.availableModels.filter((m) => typeof m === 'string') : [];
+        const models = [...new Set([...CLAUDE_MODELS, ...configured])].filter(id => NAME.test(id) && id !== 'default')
+            .map(id => ({ id, reasoningLevels: CLAUDE_EFFORT_LEVELS }));
+        agents.push({ kind: 'claude', version: parseVersion(claudeVersion), models, warnings: [] });
+    }
+    const codexVersion = await version('codex');
+    if (codexVersion !== null) {
+        const codexHome = env.CODEX_HOME ?? join(home, '.codex');
+        const warnings = [];
+        const cache = parseJson(await read(join(codexHome, 'models_cache.json')));
+        const models = Array.isArray(cache?.models) ? cache.models
+            .filter((m) => m?.visibility === 'list' && typeof m.slug === 'string' && NAME.test(m.slug))
+            .map((m) => {
+            const levels = (Array.isArray(m.supported_reasoning_levels) ? m.supported_reasoning_levels : [])
+                .map((level) => typeof level === 'string' ? level : level?.effort)
+                .filter((level) => typeof level === 'string' && NAME.test(level) && level !== 'default');
+            const fallback = typeof m.default_reasoning_level === 'string' && levels.includes(m.default_reasoning_level) ? m.default_reasoning_level : undefined;
+            return { id: m.slug, displayName: typeof m.display_name === 'string' ? m.display_name.slice(0, 100) : undefined,
+                reasoningLevels: levels.slice(0, 16), defaultReasoning: fallback };
+        }).slice(0, 64) : [];
+        if (models.length === 0)
+            warnings.push('No Codex model list found in models_cache.json. Run codex once to refresh it; only the default model is offered.');
+        const configured = defaultCodexModel(await read(join(codexHome, 'config.toml')));
+        if (configured && models.length > 0 && !models.some(m => m.id === configured))
+            warnings.push(`The default model "${configured}" from config.toml is not in the Codex model list and may be rejected; pick a model explicitly.`);
+        agents.push({ kind: 'codex', version: parseVersion(codexVersion), models, warnings });
+    }
+    const profiles = parseProfiles(await read(profilesPath(home)), home, problems);
+    for (const profile of profiles)
+        if (!agents.some(agent => agent.kind === profile.agent))
+            problems.push(`Profile "${profile.name}" uses ${profile.agent}, which is not installed.`);
+    return {
+        capabilities: { agents, profiles: profiles.map(p => ({ name: p.name, agent: p.agent, model: p.model, reasoning: p.reasoning,
+                workdir: p.workdir ? basename(p.workdir) : undefined, ...(p.sandbox ? { sandbox: true } : {}) })) },
+        profiles,
+        problems,
+    };
+}
+export function parseProfiles(text, home, problems = []) {
+    if (text === null)
+        return [];
+    const parsed = parseJson(text);
+    if (!Array.isArray(parsed?.profiles)) {
+        problems.push(`${profilesPath(home)} must contain { "profiles": [...] }.`);
+        return [];
+    }
+    const profiles = [];
+    for (const raw of parsed.profiles) {
+        const name = raw?.name;
+        if (typeof name !== 'string' || !NAME.test(name)) {
+            problems.push('Skipped a profile without a valid name.');
+            continue;
+        }
+        if (raw.agent !== 'claude' && raw.agent !== 'codex') {
+            problems.push(`Profile "${name}" needs "agent": "claude" or "codex".`);
+            continue;
+        }
+        if (profiles.some(p => p.name === name)) {
+            problems.push(`Profile "${name}" is declared twice.`);
+            continue;
+        }
+        const optional = (key) => typeof raw[key] === 'string' && NAME.test(raw[key]) ? raw[key] : undefined;
+        if (raw.model !== undefined && !optional('model') || raw.reasoning !== undefined && !optional('reasoning')) {
+            problems.push(`Profile "${name}" has an invalid model or reasoning.`);
+            continue;
+        }
+        if (raw.sandbox !== undefined && typeof raw.sandbox !== 'boolean') {
+            problems.push(`Profile "${name}" sandbox must be true or false.`);
+            continue;
+        }
+        if (raw.args !== undefined && (!Array.isArray(raw.args) || raw.args.some(arg => typeof arg !== 'string'))) {
+            problems.push(`Profile "${name}" args must be a list of strings.`);
+            continue;
+        }
+        profiles.push({ name, agent: raw.agent, model: optional('model'), reasoning: optional('reasoning'),
+            workdir: typeof raw.workdir === 'string' && raw.workdir.length > 0 ? expandHome(raw.workdir, home) : undefined,
+            args: raw.args ?? [], ...(raw.sandbox === true ? { sandbox: true } : {}) });
+    }
+    return profiles.slice(0, 32);
+}
+export function expandHome(path, home = homedir()) {
+    const expanded = path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path;
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+/** Reads the top-level model key only; profiles and providers further down the file are ignored. */
+export function defaultCodexModel(toml) {
+    if (!toml)
+        return undefined;
+    for (const line of toml.split(/\r?\n/)) {
+        if (/^\s*\[/.test(line))
+            return undefined;
+        const match = /^\s*model\s*=\s*"([^"]+)"/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function parseVersion(output) {
+    return (/\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?/.exec(output)?.[0] ?? output.trim()).slice(0, 100) || undefined;
+}
+function parseJson(text) {
+    if (text === null)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === 'object' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function commandVersion(command) {
+    return new Promise(resolvePromise => {
+        execFile(command, ['--version'], { timeout: 15_000, windowsHide: true, shell: process.platform === 'win32' }, (error, stdout) => resolvePromise(error ? null : stdout.toString()));
+    });
+}

package/dist/agents-run.js

@@ -0,0 +1,174 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT = 'default';
+/** Read-only tools Claude Code may use in a sandboxed run; MCP servers from the assignment are added per server. */
+export const CLAUDE_SANDBOX_TOOLS = ['Read', 'Grep', 'Glob', 'WebSearch', 'WebFetch'];
+export const SANDBOX_NOTE = '\n\nThis run is sandboxed: you can read files, search and use the provided MCP tools, but you cannot change files or run ' +
+    'commands that modify anything. Give your final answer as your last message; writing SKILLSHARE_AGENT_RESULT may not be possible.';
+/**
+ * Builds the agent invocation. The prompt goes to stdin and tokens to environment variables, so neither
+ * appears in the process list. Agents run without permission prompts, with the user's own configuration.
+ */
+export function isSandboxed(assignment, options) {
+    return options.sandbox === true || options.profile?.sandbox === true || assignment.configuration.sandbox === true;
+}
+export function buildAgentCommand(assignment, options) {
+    const sandbox = isSandboxed(assignment, options);
+    const { configuration } = assignment;
+    const env = { SKILLSHARE_AGENT_RESULT: join(options.directory, 'result.md'), SKILLSHARE_TASK_ID: assignment.taskId };
+    const servers = assignment.mcpServers.map((server, index) => {
+        const variable = `SKILLSHARE_MCP_TOKEN_${index}`;
+        env[variable] = server.bearerToken;
+        return { name: server.name.replace(/[^A-Za-z0-9_-]/g, '_') || `server_${index}`, url: server.url, variable };
+    });
+    const cwd = options.profile?.workdir ?? options.workdir;
+    const extra = options.profile?.args ?? [];
+    if (configuration.agent === 'claude') {
+        // A sandboxed run never prompts: anything outside the read-only allowlist is denied.
+        const args = ['-p', '--output-format', 'json', ...(sandbox
+                ? ['--permission-mode', 'dontAsk', '--allowedTools', ...CLAUDE_SANDBOX_TOOLS, ...servers.map(server => `mcp__${server.name}`)]
+                : ['--dangerously-skip-permissions'])];
+        if (configuration.model !== DEFAULT)
+            args.push('--model', configuration.model);
+        if (configuration.reasoning !== DEFAULT)
+            args.push('--effort', configuration.reasoning);
+        if (servers.length > 0)
+            args.push('--mcp-config', join(options.directory, 'mcp.json'));
+        return { command: 'claude', args: [...args, ...extra], env, cwd };
+    }
+    const args = ['exec', '--skip-git-repo-check', ...(sandbox ? ['--sandbox', 'read-only', '-c', 'approval_policy="never"'] : ['--dangerously-bypass-approvals-and-sandbox']),
+        '--output-last-message', join(options.directory, 'last-message.md')];
+    if (configuration.model !== DEFAULT)
+        args.push('-m', configuration.model);
+    if (configuration.reasoning !== DEFAULT)
+        args.push('-c', `model_reasoning_effort=${JSON.stringify(configuration.reasoning)}`);
+    for (const server of servers)
+        args.push('-c', `mcp_servers.${server.name}.url=${JSON.stringify(server.url)}`, '-c', `mcp_servers.${server.name}.bearer_token_env_var=${JSON.stringify(server.variable)}`);
+    return { command: 'codex', args: [...args, ...extra, '-'], env, cwd };
+}
+export function claudeMcpConfig(servers) {
+    return JSON.stringify({
+        mcpServers: Object.fromEntries(servers.map((server, index) => [server.name.replace(/[^A-Za-z0-9_-]/g, '_') || `server_${index}`,
+            { type: 'http', url: server.url, headers: { Authorization: `Bearer \${SKILLSHARE_MCP_TOKEN_${index}}` } }])),
+    }, null, 2);
+}
+/** Reads Claude Code's --output-format json summary. */
+export function parseClaudeOutput(stdout) {
+    try {
+        const data = JSON.parse(stdout.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? '');
+        const usage = data.usage ?? {};
+        const input = [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens]
+            .filter((value) => typeof value === 'number');
+        return {
+            result: typeof data.result === 'string' ? data.result : undefined,
+            isError: data.is_error === true,
+            stats: {
+                durationMs: typeof data.duration_ms === 'number' ? data.duration_ms : undefined,
+                turns: typeof data.num_turns === 'number' ? data.num_turns : undefined,
+                costUsd: typeof data.total_cost_usd === 'number' ? data.total_cost_usd : undefined,
+                inputTokens: input.length > 0 ? input.reduce((a, b) => a + b, 0) : undefined,
+                outputTokens: typeof usage.output_tokens === 'number' ? usage.output_tokens : undefined,
+            },
+        };
+    }
+    catch {
+        return { isError: false, stats: {} };
+    }
+}
+export async function runAgent(assignment, options) {
+    const now = options.now ?? Date.now;
+    const started = now();
+    const directory = await mkdtemp(join(tmpdir(), 'skillshare-agent-'));
+    try {
+        const command = buildAgentCommand(assignment, { directory, workdir: options.workdir, profile: options.profile, sandbox: options.sandbox });
+        if (assignment.configuration.agent === 'claude' && assignment.mcpServers.length > 0)
+            await writeFile(join(directory, 'mcp.json'), claudeMcpConfig(assignment.mcpServers), { mode: 0o600 });
+        const prompt = assignment.prompt + (isSandboxed(assignment, options) ? SANDBOX_NOTE : '');
+        const outcome = await execute(command, prompt, Math.max(1, assignment.timeoutSeconds) * 1000, options.signal, options.spawnAgent ?? spawn);
+        const measured = { durationMs: now() - started };
+        const claude = assignment.configuration.agent === 'claude' ? parseClaudeOutput(outcome.stdout) : undefined;
+        const stats = { ...measured, ...Object.fromEntries(Object.entries(claude?.stats ?? {}).filter(([, value]) => value !== undefined)) };
+        if (outcome.cancelled)
+            return { ok: false, reason: 'Cancelled on request.', cancelled: true, stats };
+        if (outcome.timedOut)
+            return { ok: false, reason: `The agent did not finish within ${assignment.timeoutSeconds} seconds.`, cancelled: false, stats };
+        if (outcome.spawnError)
+            return { ok: false, reason: `Could not start ${command.command}: ${outcome.spawnError}`, cancelled: false, stats };
+        const answer = await readAnswer(directory, assignment.configuration.agent, claude?.result);
+        if (outcome.code !== 0 || claude?.isError) {
+            const detail = (claude?.isError ? claude.result : undefined) ?? lastLines(outcome.stderr) ?? `exit code ${outcome.code}`;
+            return { ok: false, reason: `${command.command} failed: ${detail}`.slice(0, 500), cancelled: false, stats };
+        }
+        if (!answer)
+            return { ok: false, reason: 'The agent finished without an answer.', cancelled: false, stats };
+        return { ok: true, markdown: answer, stats };
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+async function readAnswer(directory, agent, claudeResult) {
+    for (const file of ['result.md', ...(agent === 'codex' ? ['last-message.md'] : [])]) {
+        try {
+            const text = (await readFile(join(directory, file), 'utf8')).trim();
+            if (text)
+                return text;
+        }
+        catch { }
+    }
+    return claudeResult?.trim() || undefined;
+}
+function lastLines(text) {
+    const lines = text.trim().split(/\r?\n/).filter(line => line.trim()).slice(-3).join(' ').trim();
+    return lines ? lines.slice(-300) : undefined;
+}
+function execute(command, input, timeoutMs, signal, spawnAgent) {
+    return new Promise(resolvePromise => {
+        const posix = process.platform !== 'win32';
+        const child = spawnAgent(command.command, command.args, {
+            cwd: command.cwd, env: { ...process.env, ...command.env }, stdio: ['pipe', 'pipe', 'pipe'],
+            // A separate process group lets cancellation stop the agent's own child processes too.
+            detached: posix, windowsHide: true, shell: !posix,
+        });
+        let stdout = '';
+        let stderr = '';
+        let cancelled = false;
+        let timedOut = false;
+        let settled = false;
+        const stop = () => {
+            const kill = (sig) => {
+                try {
+                    if (posix && child.pid)
+                        process.kill(-child.pid, sig);
+                    else
+                        child.kill(sig);
+                }
+                catch { }
+            };
+            kill('SIGTERM');
+            setTimeout(() => kill('SIGKILL'), 5000).unref();
+        };
+        const onAbort = () => { cancelled = true; stop(); };
+        const timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolvePromise(outcome);
+        };
+        child.stdout?.on('data', chunk => { if (stdout.length < 2_000_000)
+            stdout += chunk; });
+        child.stderr?.on('data', chunk => { stderr = (stderr + chunk).slice(-4000); });
+        child.on('error', error => finish({ code: null, stdout, stderr, cancelled, timedOut, spawnError: error.message }));
+        child.on('close', code => finish({ code, stdout, stderr, cancelled, timedOut }));
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(input);
+        if (signal.aborted)
+            onAbort();
+    });
+}

package/dist/agents.js

@@ -0,0 +1,225 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { hostname, platform } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { detectAgents, profilesPath } from './agents-detect.js';
+import { runAgent } from './agents-run.js';
+import { readCliVersion } from './help.js';
+const root = '/api/agents';
+const PROFILE_HINT = 'Declare named profiles in ' + profilesPath() + ' to set a working directory or extra arguments.';
+export class AgentsHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+async function send(client, method, path, body, signal) {
+    const response = await client.request(path, { method, headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body), signal });
+    if (!response.ok) {
+        let message = `Skillshare returned HTTP ${response.status}.`;
+        try {
+            message = (await response.json()).error ?? message;
+        }
+        catch { }
+        throw new AgentsHttpError(response.status, message);
+    }
+    return response.status === 204 ? undefined : await response.json();
+}
+/** One stable listener id per Skillshare server and account, so the web keeps routes across restarts. */
+export async function loadListenerId(appDirectory, baseUrl, userId) {
+    const key = createHash('sha256').update(baseUrl + '\0' + userId).digest('hex').slice(0, 24);
+    const file = join(appDirectory, 'agents', `listener-${key}.json`);
+    try {
+        const stored = JSON.parse(await readFile(file, 'utf8'));
+        if (typeof stored.id === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(stored.id))
+            return stored.id;
+    }
+    catch { }
+    const id = randomBytes(12).toString('base64url');
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFile(file, JSON.stringify({ id }, null, 2), { mode: 0o600 });
+    return id;
+}
+export async function runAgentsCommand(client, args, flags, appDirectory) {
+    const action = args[0];
+    if (action === 'status') {
+        const detected = await detectAgents();
+        const user = await client.get('/api/auth/me');
+        const listenerId = await loadListenerId(appDirectory, client.baseUrl, user.id);
+        if (flags.json === 'true') {
+            console.log(JSON.stringify({ listenerId, server: client.baseUrl, ...detected.capabilities, problems: detected.problems }, null, 2));
+            return;
+        }
+        console.log(renderDetected(listenerId, client.baseUrl, detected));
+        return;
+    }
+    if (action !== 'listen')
+        throw new Error('agents requires listen or status.');
+    const max = flags['max-concurrency'] === undefined ? undefined : Number(flags['max-concurrency']);
+    if (max !== undefined && (!Number.isInteger(max) || max < 1 || max > 4))
+        throw new Error('--max-concurrency must be between 1 and 4.');
+    const workdir = resolve(flags.workdir ?? process.cwd());
+    const sandbox = flags.sandbox === 'true';
+    const user = await client.get('/api/auth/me');
+    const listenerId = await loadListenerId(appDirectory, client.baseUrl, user.id);
+    const abort = new AbortController();
+    const stop = () => abort.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    console.log(sandbox
+        ? 'Sandboxed: agents may read files, search and use the Skillshare MCP tools, but cannot change files or run commands that modify anything.'
+        : 'Agents run with your full local permissions and configuration, without permission prompts. Use --sandbox to keep them read-only.');
+    try {
+        await listen({ client, listenerId, name: flags.name, workdir, maxConcurrency: max, sandbox, signal: abort.signal, onProgress: console.log });
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+    }
+}
+export function renderDetected(listenerId, server, detected) {
+    const lines = [`Listener ${listenerId} on ${server}`];
+    if (detected.capabilities.agents.length === 0)
+        lines.push('No supported agent found. Install Claude Code (claude) or Codex (codex) and make sure it is on PATH.');
+    for (const agent of detected.capabilities.agents) {
+        lines.push(`${agent.kind === 'claude' ? 'Claude Code' : 'Codex'} ${agent.version ?? ''}`.trimEnd());
+        for (const model of agent.models)
+            lines.push(`  ${model.id}${model.reasoningLevels.length ? `  (${model.reasoningLevels.join(', ')})` : ''}`);
+        for (const warning of agent.warnings)
+            lines.push(`  ! ${warning}`);
+    }
+    if (detected.profiles.length === 0)
+        lines.push(PROFILE_HINT);
+    for (const profile of detected.profiles)
+        lines.push(`Profile ${profile.name}: ${profile.agent}${profile.model ? ' ' + profile.model : ''}${profile.reasoning ? ' ' + profile.reasoning : ''}${profile.workdir ? ' in ' + profile.workdir : ''}${profile.sandbox ? ' (sandbox)' : ''}`);
+    for (const problem of detected.problems)
+        lines.push(`! ${problem}`);
+    return lines.join('\n');
+}
+export async function listen(options) {
+    const detect = options.detect ?? (() => detectAgents());
+    const run = options.run ?? runAgent;
+    const wait = options.wait ?? (async (ms, signal) => { await delay(ms, undefined, { signal }); });
+    const now = options.now ?? Date.now;
+    const log = options.onProgress ?? (() => { });
+    const running = new Map();
+    let detected = await detect();
+    let registeredFingerprint = '';
+    let detectedAt = now();
+    let failures = 0;
+    const capabilities = () => options.sandbox ? { ...detected.capabilities, sandbox: true } : detected.capabilities;
+    async function register() {
+        const fingerprint = JSON.stringify(capabilities());
+        const registered = await send(options.client, 'PUT', `${root}/listeners/${options.listenerId}`, {
+            name: options.name ?? hostname(), host: hostname(), os: platform(), cliVersion: readCliVersion(), maxConcurrency: options.maxConcurrency,
+            capabilities: capabilities(),
+        }, options.signal);
+        registeredFingerprint = fingerprint;
+        for (const problem of detected.problems)
+            log(`! ${problem}`);
+        log(`Listening as "${registered.name}" with ${registered.effectiveConcurrency} slot(s): ${describe(detected)}. Choose what runs where under Connected agents on ${options.client.baseUrl}.`);
+    }
+    async function report(assignment, result) {
+        const path = `${root}/tasks/${assignment.taskId}/${result.ok ? 'result' : 'failure'}`;
+        const body = result.ok ? { leaseToken: assignment.leaseToken, markdown: result.markdown, stats: result.stats }
+            : { leaseToken: assignment.leaseToken, reason: result.reason, cancelled: result.cancelled, stats: result.stats };
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                await send(options.client, 'POST', path, body);
+                return;
+            }
+            catch (error) {
+                // A rejected lease means the server already moved on; retrying cannot help.
+                if (error instanceof AgentsHttpError && error.status >= 400 && error.status < 500) {
+                    log(`Task ${assignment.taskId} result was not accepted: ${error.message}`);
+                    return;
+                }
+                if (attempt < 4)
+                    await delay(2000 * (attempt + 1)).catch(() => { });
+            }
+        }
+        log(`Task ${assignment.taskId} result could not be delivered; the server will retry the task after its lease expires.`);
+    }
+    function start(assignment) {
+        if (running.has(assignment.taskId))
+            return;
+        const abort = new AbortController();
+        const profile = assignment.configuration.profile ? detected.profiles.find(p => p.name === assignment.configuration.profile) : undefined;
+        log(`Started task ${assignment.taskId} "${assignment.title}" with ${label(assignment)}.`);
+        const done = (async () => {
+            let result;
+            try {
+                result = await run(assignment, { workdir: options.workdir, profile, sandbox: options.sandbox, signal: abort.signal });
+            }
+            catch (error) {
+                result = { ok: false, reason: `The listener could not run the agent: ${error instanceof Error ? error.message : String(error)}`, cancelled: false, stats: {} };
+            }
+            log(result.ok ? `Finished task ${assignment.taskId}.` : `${result.cancelled ? 'Cancelled' : 'Failed'} task ${assignment.taskId}: ${result.reason}`);
+            await report(assignment, result);
+            running.delete(assignment.taskId);
+        })();
+        running.set(assignment.taskId, { assignment, abort, done });
+    }
+    try {
+        while (!options.signal.aborted) {
+            try {
+                if (now() - detectedAt > (options.redetectMs ?? 5 * 60_000)) {
+                    detected = await detect();
+                    detectedAt = now();
+                }
+                if (registeredFingerprint !== JSON.stringify(capabilities()))
+                    await register();
+                const polledAt = now();
+                const response = await send(options.client, 'POST', `${root}/listeners/${options.listenerId}/poll`, {
+                    // A task that is already stopping is not reported, otherwise the server would answer every poll with its cancellation.
+                    running: [...running.values()].filter(r => !r.abort.signal.aborted)
+                        .map(r => ({ taskId: Number(r.assignment.taskId), leaseToken: r.assignment.leaseToken })),
+                    waitSeconds: options.pollWaitSeconds ?? 25,
+                }, options.signal);
+                failures = 0;
+                for (const id of response.cancel)
+                    running.get(id)?.abort.abort();
+                for (const assignment of response.assignments)
+                    start(assignment);
+                if (response.assignments.length === 0 && now() - polledAt < 1000)
+                    await wait(1000, options.signal).catch(() => { });
+            }
+            catch (error) {
+                if (options.signal.aborted)
+                    break;
+                if (error instanceof AgentsHttpError && error.status === 404) {
+                    registeredFingerprint = '';
+                    continue;
+                }
+                failures++;
+                if (failures === 1)
+                    log(`Skillshare is unreachable or rejected the listener (${error instanceof Error ? error.message : String(error)}). Retrying.`);
+                try {
+                    await wait(Math.min(60_000, 2000 * 2 ** Math.min(failures, 5)), options.signal);
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+    }
+    finally {
+        for (const task of running.values())
+            task.abort.abort();
+        await Promise.all([...running.values()].map(task => task.done));
+    }
+}
+function label(assignment) {
+    const { configuration } = assignment;
+    if (configuration.profile)
+        return `profile ${configuration.profile}`;
+    return [configuration.agent === 'claude' ? 'Claude Code' : 'Codex', configuration.model, configuration.reasoning]
+        .filter(part => part !== 'default').join(' ');
+}
+function describe(detected) {
+    const agents = detected.capabilities.agents.map(a => `${a.kind === 'claude' ? 'Claude Code' : 'Codex'} ${a.version ?? ''}`.trim());
+    const profiles = detected.profiles.length ? `, profiles ${detected.profiles.map(p => p.name).join(', ')}` : '';
+    return (agents.length ? agents.join(', ') : 'no supported agent found') + profiles;
+}

package/dist/help.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 export const GLOBAL_FLAGS = ['token', 'server', 'help'];
-export const BOOLEAN_FLAGS = new Set(['dry-run', 'force', 'headless', 'help']);
+export const BOOLEAN_FLAGS = new Set(['dry-run', 'force', 'headless', 'help', 'json', 'sandbox']);
 export const COMMANDS = [
     {
         name: 'login',
@@ -19,20 +19,21 @@ export const COMMANDS = [
     {
         name: 'whoami',
         summary: 'Show the signed-in user',
-        usage: ['whoami'],
-        flags: [],
+        usage: ['whoami [--json]'],
+        flags: ['json'],
     },
     {
         name: 'list',
         summary: 'List skills in the registry',
-        usage: ['list'],
-        flags: [],
+        usage: ['list [--json]'],
+        flags: ['json'],
     },
     {
         name: 'show',
         summary: 'Show a skill or one of its versions',
-        usage: ['show <skillId> [version]'],
-        flags: [],
+        usage: ['show <skillId|skillName> [version] [--json]'],
+        examples: ['skillshare show "Prompt Lint"', 'skillshare show 12 0.1.0 --json'],
+        flags: ['json'],
     },
     {
         name: 'install',
@@ -73,23 +74,25 @@ export const COMMANDS = [
             ['--skill-id <id>', 'Publish to this existing skill'],
             ['--name <name>', 'Name for a new skill (defaults to SKILL.md)'],
             ['--description <text>', 'Description for a new skill (defaults to SKILL.md)'],
+            ['--json', 'Print the server response as JSON'],
         ],
         examples: ['skillshare upload ./prompt-lint --version 0.2.0'],
-        flags: ['version', 'skill-id', 'name', 'description'],
+        flags: ['version', 'skill-id', 'name', 'description', 'json'],
     },
     {
         name: 'pages',
         summary: 'Publish and inspect authenticated pages',
         usage: [
-            'pages list',
-            'pages show <slug>',
-            'pages runtime <slug>',
-            'pages upload <directory> [--slug <slug>]',
+            'pages list [--json]',
+            'pages show <slug> [--json]',
+            'pages runtime <slug> [--json]',
+            'pages upload <directory> [--slug <slug>] [--json]',
             'pages dev [directory] [--slug <slug>] [--port <port>] [--build <command> --watch-dir <sources>]',
             '  [--celld <executable>] [--user-id <id>] [--user-name <name>] [--user-email <email>]',
         ],
+        description: 'An upload replaces all content of the page. Without --slug the directory name is used; build output folders such as dist need an explicit --slug. Pages owned by someone else are refused unless you are an admin.',
         examples: ['skillshare pages upload ./site --slug release-notes', 'skillshare pages dev . --slug my-app'],
-        flags: ['slug'],
+        flags: ['slug', 'json'],
     },
     {
         name: 'teams',
@@ -97,12 +100,24 @@ export const COMMANDS = [
         usage: [
             'teams login [local] [--browser chrome|msedge|chromium] [--headless] [--browser-profile <directory>]',
             'teams watch [local] [--browser chrome|msedge|chromium]',
-            'teams status | test | logout',
+            'teams status | test [--json]',
+            'teams logout',
             'teams access readOnly|fullAccess',
             'teams upload <file>',
             'teams download <url> --output <new-file>',
         ],
-        flags: ['browser', 'headless', 'browser-profile', 'output'],
+        flags: ['browser', 'headless', 'browser-profile', 'output', 'json'],
+    },
+    {
+        name: 'agents',
+        summary: 'Run Claude Code or Codex tasks from Skillshare on this computer',
+        usage: [
+            'agents listen [local] [--name <name>] [--workdir <directory>] [--max-concurrency <1-4>] [--sandbox]',
+            'agents status [local] [--json]',
+        ],
+        description: 'A listener reports the installed agents, their models and reasoning levels, and the local profiles from ~/.config/skillshare/agents.json. Choose which listener and configuration runs each kind of task under Connected agents in Skillshare. Agents run with your full local permissions, without permission prompts, unless --sandbox (or "sandbox": true in a profile) keeps them read-only.',
+        examples: ['skillshare agents status', 'skillshare agents listen --workdir ~/Research'],
+        flags: ['name', 'workdir', 'max-concurrency', 'sandbox', 'json'],
     },
     {
         name: 'git',
@@ -131,6 +146,7 @@ export function renderUsage(defaultUrl) {
         'Options:',
         '  --token <token>  Bearer token for API requests (overrides SKILLSHARE_TOKEN)',
         '  --server <url>   Skillshare origin for login and Teams commands',
+        '  --json           Print machine-readable JSON (whoami, list, show, upload, pages, teams, agents)',
         '  -h, --help       Show help for a command',
         '  -v, --version    Show the CLI version',
         '',

package/dist/index.js

@@ -1,8 +1,10 @@
-import { assertCredentialDestination, runTeamsCommand } from './teams.js';
+import { assertCredentialDestination, resolveTeamsObjectId, runTeamsCommand } from './teams.js';
+import { runAgentsCommand } from './agents.js';
 import { formatUnknownCommand, parseCliArgs } from './cli-args.js';
 import { findCommand, readCliVersion, renderCommandHelp, renderUsage } from './help.js';
 import { inspectInstallTarget, installFilesAtomically } from './install-files.js';
-import { preparePageFiles } from './pages.js';
+import { preparePageFiles, resolvePageSlug } from './pages.js';
+import { formatByteSize, formatDateTime, pageUrl, plural, renderPageDetail, renderPageList, renderPageRuntime, renderSkillDetail, renderSkillList, renderSkillVersion, renderUser, } from './output.js';
 import { runPageDev } from './pages-dev.js';
 import { createServer } from 'node:http';
 import { createHash, randomBytes } from 'node:crypto';
@@ -72,6 +74,8 @@ const AGENTS = [
     { value: 'adal', label: 'AdaL', projectPath: '.adal/skills', globalPath: '.adal/skills' },
 ];
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
+// Progress goes to stderr with --json so stdout stays machine-readable.
+let statusOutput = process.stdout;
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -102,6 +106,13 @@ async function main() {
         console.log(renderCommandHelp(commandSpec));
         return;
     }
+    const json = isFlagEnabled(options.flags, 'json');
+    if (json) {
+        statusOutput = process.stderr;
+    }
+    const print = (value, human) => {
+        console.log(json ? JSON.stringify(value, null, 2) : human());
+    };
     if ((command === 'pages' || command === 'page') && options.positionals[0] === 'dev') {
         await runPageDev(options.positionals[1] ?? '.', options.flags);
         return;
@@ -122,7 +133,23 @@ async function main() {
             assertCredentialDestination(baseUrl);
             if (!options.token && !await loadSession(baseUrl))
                 await login(baseUrl);
-            await runTeamsCommand(await createClient(baseUrl, options.token), options.positionals, options.flags, APP_DIR);
+            const teamsClient = await createClient(baseUrl, options.token);
+            const action = options.positionals[0];
+            if (!options.token && (action === 'login' || action === 'watch')
+                && !resolveTeamsObjectId(await teamsClient.get('/api/auth/me'))) {
+                // A browser sign-in lets the server record the Entra object id for this account.
+                console.log('Linking your Microsoft account to Skillshare. Sign in once more in the browser.');
+                await login(baseUrl);
+            }
+            await runTeamsCommand(teamsClient, options.positionals, options.flags, APP_DIR);
+            return;
+        }
+        case 'agents': {
+            const baseUrl = options.flags.server ?? (options.positionals[1] === 'local' ? LOCAL_URL : await resolveActiveBaseUrl());
+            assertCredentialDestination(baseUrl);
+            if (!options.token && !await loadSession(baseUrl))
+                await login(baseUrl);
+            await runAgentsCommand(await createClient(baseUrl, options.token), options.positionals, options.flags, APP_DIR);
             return;
         }
         case 'git': {
@@ -151,27 +178,28 @@ async function main() {
             switch (command) {
                 case 'whoami': {
                     const user = await client.get('/api/auth/me');
-                    console.log(JSON.stringify(user, null, 2));
+                    print(user, () => renderUser(user, client.baseUrl));
                     return;
                 }
                 case 'list': {
                     const skills = await client.get('/api/skills');
-                    for (const skill of skills) {
-                        console.log(`${skill.id}\t${skill.latestVersion}\t${skill.name}`);
-                    }
+                    print(skills, () => renderSkillList(skills));
                     return;
                 }
                 case 'show': {
-                    const skillId = options.positionals[0];
+                    const skillRef = options.positionals[0];
                     const version = options.positionals[1];
-                    if (!skillId) {
-                        throw new Error('show requires <skillId>');
+                    if (!skillRef) {
+                        throw new Error('show requires <skillId|skillName>');
+                    }
+                    const skill = resolveSkillReference(await client.get('/api/skills'), skillRef);
+                    if (version) {
+                        const detail = await client.get(`/api/skills/${skill.id}/versions/${encodeURIComponent(version)}`);
+                        print(detail, () => renderSkillVersion(skill.name, detail));
+                        return;
                     }
-                    const resource = version
-                        ? `/api/skills/${skillId}/versions/${version}`
-                        : `/api/skills/${skillId}`;
-                    const data = await client.get(resource);
-                    console.log(JSON.stringify(data, null, 2));
+                    const detail = await client.get(`/api/skills/${skill.id}`);
+                    print(detail, () => renderSkillDetail(detail));
                     return;
                 }
                 case 'upload': {
@@ -190,14 +218,14 @@ async function main() {
                             description: options.flags.description,
                             version,
                         });
-                        console.log(JSON.stringify(created.response, null, 2));
+                        print(created.response, () => `Created skill #${created.detail.id} "${created.detail.name}" with version ${version}.`);
                     }
                     else {
                         const published = await publishSkillFromDirectory(client, localSkill, {
                             skillId: existingSkill.id,
                             version,
                         });
-                        console.log(JSON.stringify(published.response, null, 2));
+                        print(published.response, () => `Published ${published.detail.name}@${published.response.version} (skill #${published.detail.id}).`);
                     }
                     return;
                 }
@@ -301,16 +329,21 @@ async function main() {
                     const action = options.positionals[0] ?? 'list';
                     if (action === 'list') {
                         const pages = await client.get('/api/pages');
-                        for (const page of pages) {
-                            console.log(`${page.slug}\t${page.kind}\t${page.fileCount}\t${page.ownerDisplayName}`);
-                        }
+                        print(pages, () => renderPageList(pages));
                         return;
                     }
                     if (action === 'show' || action === 'runtime') {
                         const slug = options.positionals[1];
                         if (!slug)
                             throw new Error(`pages ${action} requires <slug>`);
-                        console.log(JSON.stringify(await client.get(`/api/pages/${encodeURIComponent(slug)}${action === 'runtime' ? '/runtime' : ''}`), null, 2));
+                        if (action === 'show') {
+                            const page = await client.get(`/api/pages/${encodeURIComponent(slug)}`);
+                            print(page, () => renderPageDetail(page, client.baseUrl));
+                        }
+                        else {
+                            const runtime = await client.get(`/api/pages/${encodeURIComponent(slug)}/runtime`);
+                            print(runtime, () => renderPageRuntime(slug, runtime));
+                        }
                         return;
                     }
                     if (action === 'upload') {
@@ -318,14 +351,15 @@ async function main() {
                         if (!directory)
                             throw new Error('pages upload requires <directory>');
                         const resolvedDirectory = resolve(directory);
-                        const slug = normalizePageSlug(options.flags.slug ?? basename(resolvedDirectory));
+                        const slug = resolvePageSlug(resolvedDirectory, options.flags.slug);
+                        const existing = await describePageUploadTarget(client, slug);
                         const pageFiles = await loadLocalPageFiles(resolvedDirectory);
-                        const uploadStatus = spinner({ indicator: 'timer' });
-                        uploadStatus.start(`Uploading ${pageFiles.files.length} files (${formatByteSize(pageFiles.totalBytes)}) to /p/${slug}/`);
+                        const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
+                        uploadStatus.start(`${existing ? 'Replacing' : 'Creating'} /p/${slug}/ with ${plural(pageFiles.files.length, 'file')} (${formatByteSize(pageFiles.totalBytes)})`);
                         try {
                             const detail = await client.replacePageContent(slug, pageFiles.files);
-                            uploadStatus.stop(`Published /p/${detail.slug}/ with ${detail.files.length} files`);
-                            console.log(JSON.stringify(detail, null, 2));
+                            uploadStatus.stop(`Published /p/${detail.slug}/ as revision ${detail.contentRevision} with ${plural(detail.files.length, 'file')}`);
+                            print(detail, () => `Open ${pageUrl(client.baseUrl, detail.slug)}`);
                         }
                         catch (error) {
                             uploadStatus.clear();
@@ -401,7 +435,7 @@ async function checkInstalledSkillsForUpdates(client) {
     if (records.length === 0) {
         return [];
     }
-    const status = spinner();
+    const status = spinner({ output: statusOutput });
     status.start(`Checking ${records.length} installed skill${records.length === 1 ? '' : 's'} for updates`);
     const problems = [];
     try {
@@ -859,7 +893,7 @@ async function promptConfirm(message, initialValue = false) {
 }
 async function loadLocalSkillContext(directory, baseUrl) {
     const resolvedDirectory = resolve(directory);
-    const scanStatus = spinner({ indicator: 'timer' });
+    const scanStatus = spinner({ indicator: 'timer', output: statusOutput });
     scanStatus.start(`Scanning ${resolvedDirectory}`);
     let filePlans;
     try {
@@ -871,7 +905,7 @@ async function loadLocalSkillContext(directory, baseUrl) {
     }
     scanStatus.stop(`Found ${filePlans.length} file${filePlans.length === 1 ? '' : 's'} in ${resolvedDirectory}`);
     const totalBytes = filePlans.reduce((sum, file) => sum + file.size, 0);
-    const readProgress = progress({ max: Math.max(filePlans.length, 1), size: 32 });
+    const readProgress = progress({ max: Math.max(filePlans.length, 1), size: 32, output: statusOutput });
     if (filePlans.length > 0) {
         readProgress.start(`Reading files 0/${filePlans.length}`);
     }
@@ -911,7 +945,7 @@ async function loadLocalPageFiles(directory) {
 async function createSkillFromDirectory(client, localSkill, input) {
     const name = normalizeText(input.name) ?? localSkill.defaults.name;
     const description = normalizeText(input.description) ?? localSkill.defaults.description;
-    const uploadStatus = spinner({ indicator: 'timer' });
+    const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
     uploadStatus.start(`Uploading ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
     try {
         const response = await client.createSkill({
@@ -932,7 +966,7 @@ async function createSkillFromDirectory(client, localSkill, input) {
     }
 }
 async function publishSkillFromDirectory(client, localSkill, input) {
-    const uploadStatus = spinner({ indicator: 'timer' });
+    const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
     uploadStatus.start(`Uploading ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
     try {
         const response = await client.publishVersion({
@@ -1056,7 +1090,7 @@ async function downloadResponseToFile(response, destination, onBytesTransferred)
     return hash.digest('hex');
 }
 function createInstallProgressReporter(input) {
-    const installStatus = spinner({ indicator: 'timer' });
+    const installStatus = spinner({ indicator: 'timer', output: statusOutput });
     const state = {
         completedFiles: 0,
         completedTargets: 0,
@@ -1319,12 +1353,30 @@ function normalizeText(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : null;
 }
-function normalizePageSlug(value) {
-    const normalized = value.trim().toLowerCase();
-    if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(normalized)) {
-        throw new Error('Page slug must be 1-64 lowercase letters, numbers, or hyphens, and cannot start or end with a hyphen.');
+/**
+ * Reports whether an upload replaces an existing page and stops before uploading when the
+ * page belongs to someone else, so a reused slug is noticed before any files are sent.
+ */
+async function describePageUploadTarget(client, slug) {
+    let page;
+    try {
+        page = await client.get(`/api/pages/${encodeURIComponent(slug)}`);
     }
-    return normalized;
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404) {
+            statusOutput.write(`Creating a new page /p/${slug}/.\n`);
+            return null;
+        }
+        throw error;
+    }
+    const me = await client.get('/api/auth/me');
+    const isOwner = me.storedUserId != null && me.storedUserId === page.ownerUserId;
+    if (!isOwner && !me.isAdmin) {
+        throw new Error(`Page /p/${slug}/ belongs to ${page.ownerDisplayName}. Choose another --slug.`);
+    }
+    statusOutput.write(`Replacing all content of /p/${slug}/ (revision ${page.contentRevision}, ${plural(page.files.length, 'file')}, updated ${formatDateTime(page.updated)}).\n`
+        + (isOwner ? '' : `Warning: this page belongs to ${page.ownerDisplayName}; you are replacing it as an admin.\n`));
+    return page;
 }
 async function resolveExistingUploadSkill(client, localSkill, options) {
     const explicitSkillId = normalizeText(options?.explicitSkillId);
@@ -2154,20 +2206,6 @@ function guessContentType(path) {
         return 'font/woff2';
     return 'application/octet-stream';
 }
-function formatByteSize(bytes) {
-    if (!Number.isFinite(bytes) || bytes <= 0) {
-        return '0 B';
-    }
-    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
-    let value = bytes;
-    let unitIndex = 0;
-    while (value >= 1024 && unitIndex < units.length - 1) {
-        value /= 1024;
-        unitIndex += 1;
-    }
-    const decimals = value >= 10 || unitIndex === 0 ? 0 : 1;
-    return `${value.toFixed(decimals)} ${units[unitIndex]}`;
-}
 function normalizeBaseUrl(url) {
     return url.replace(/\/+$/, '');
 }

package/dist/output.js

@@ -0,0 +1,167 @@
+// Human-readable renderers for CLI commands. Every command also supports --json for scripts.
+export function formatTable(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? '').length)));
+    const line = (cells) => cells
+        .map((cell, index) => (index === cells.length - 1 ? cell : cell.padEnd(widths[index] ?? 0)))
+        .join('  ')
+        .trimEnd();
+    return [line(headers), ...rows.map(line)].join('\n');
+}
+export function formatDateTime(value) {
+    if (!value)
+        return '—';
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    const pad = (part) => String(part).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function formatByteSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    const decimals = value >= 10 || unitIndex === 0 ? 0 : 1;
+    return `${value.toFixed(decimals)} ${units[unitIndex]}`;
+}
+function fields(entries) {
+    const present = entries.filter((entry) => entry[1] !== null && entry[1] !== undefined && entry[1] !== '');
+    const width = Math.max(...present.map(([label]) => label.length + 1));
+    return present.map(([label, value]) => `${`${label}:`.padEnd(width)}  ${value}`);
+}
+export function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function fileLines(files) {
+    const width = Math.max(0, ...files.map((file) => file.nameWithPath.length));
+    return files.map((file) => `  ${file.nameWithPath.padEnd(width)}  ${formatByteSize(file.length)}`);
+}
+function limitedList(lines, limit, what) {
+    return lines.length > limit
+        ? [...lines.slice(0, limit), `  … and ${lines.length - limit} more ${what} (use --json for all)`]
+        : lines;
+}
+export function renderUser(user, server) {
+    return [
+        `${user.displayName}${user.email ? ` <${user.email}>` : ''}`,
+        ...fields([
+            ['Server', server],
+            ['Role', user.isAdmin ? 'admin' : 'user'],
+            ['Microsoft account', user.entraObjectId ? 'linked' : 'not linked yet (open Skillshare in the browser once)'],
+        ]),
+    ].join('\n');
+}
+export function renderSkillList(skills) {
+    if (skills.length === 0)
+        return 'No skills in the registry yet.';
+    return formatTable(['ID', 'NAME', 'LATEST', 'UPDATED'], skills.map((skill) => [
+        String(skill.id),
+        `${skill.name}${skill.deprecated ? ' (deprecated)' : ''}`,
+        skill.latestVersion ?? '—',
+        formatDateTime(skill.updated),
+    ]));
+}
+export function renderSkillDetail(skill) {
+    const lines = [
+        `${skill.name} (#${skill.id})${skill.deprecated ? ' — deprecated' : ''}`,
+        skill.description,
+        '',
+        ...fields([
+            ['Owner', skill.ownerDisplayName],
+            ['Latest', skill.latestVersion ?? 'no published version'],
+            ['Updated', skill.updated ? formatDateTime(skill.updated) : undefined],
+            ['Install', `skillshare install ${skill.id}`],
+        ]),
+    ];
+    if (skill.versions.length > 0) {
+        lines.push('', formatTable(['VERSION', 'PUBLISHED', 'BY', 'FILES', 'DOWNLOADS'], skill.versions.map((version) => [
+            `${version.version}${version.isLatest ? ' (latest)' : ''}`,
+            formatDateTime(version.created),
+            version.createdByDisplayName ?? '—',
+            String(version.files.length),
+            version.downloadCount === undefined ? '—' : String(version.downloadCount),
+        ])));
+    }
+    return lines.join('\n');
+}
+export function renderSkillVersion(skillName, version) {
+    const totalBytes = version.files.reduce((sum, file) => sum + file.length, 0);
+    return [
+        `${skillName} ${version.version}${version.isLatest ? ' (latest)' : ''}`,
+        ...fields([
+            ['Published', `${formatDateTime(version.created)}${version.createdByDisplayName ? ` by ${version.createdByDisplayName}` : ''}`],
+            ['Downloads', version.downloadCount],
+        ]),
+        '',
+        `Files (${version.files.length}, ${formatByteSize(totalBytes)}):`,
+        ...limitedList(fileLines(version.files), 50, 'files'),
+    ].join('\n');
+}
+export function renderPageList(pages) {
+    if (pages.length === 0)
+        return 'No pages published yet.';
+    return formatTable(['SLUG', 'KIND', 'FILES', 'SIZE', 'OWNER', 'UPDATED'], pages.map((page) => [
+        page.slug,
+        page.kind === 'celld' ? 'app' : 'static',
+        String(page.fileCount),
+        formatByteSize(page.totalBytes),
+        page.ownerDisplayName,
+        formatDateTime(page.updated),
+    ]));
+}
+export function renderPageDetail(page, baseUrl, now = new Date()) {
+    const month = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`;
+    const totalBytes = page.files.reduce((sum, file) => sum + file.length, 0);
+    return [
+        `${page.slug} (${page.kind === 'celld' ? 'application' : 'static site'})`,
+        ...fields([
+            ['URL', pageUrl(baseUrl, page.slug)],
+            ['Owner', page.ownerDisplayName],
+            ['Revision', `${page.contentRevision}, updated ${formatDateTime(page.updated)}`],
+            ['Users this month', page.monthlyUsage.find((usage) => usage.month === month)?.uniqueUsers ?? 0],
+        ]),
+        '',
+        `Files (${page.files.length}, ${formatByteSize(totalBytes)}):`,
+        ...limitedList(fileLines(page.files), 30, 'files'),
+    ].join('\n');
+}
+export function renderPageRuntime(slug, runtime, logLimit = 20) {
+    const lines = [
+        `${slug}: ${runtime.state} · revision ${runtime.revision}${runtime.processId ? ` · pid ${runtime.processId}` : ''}`,
+    ];
+    if (runtime.error)
+        lines.push(`Error: ${runtime.error}`);
+    if (runtime.logs.length > 0) {
+        const shown = runtime.logs.slice(-logLimit);
+        lines.push('', `Last ${shown.length} of ${runtime.logs.length} log lines${runtime.logs.length > shown.length ? ' (use --json for all)' : ''}:`, ...shown);
+    }
+    else {
+        lines.push('No log output yet.');
+    }
+    return lines.join('\n');
+}
+export function renderTeamsStatus(status) {
+    const state = status.requiresReconnect
+        ? 'reconnect required — run skillshare teams login'
+        : status.configured
+            ? `connected${status.identity ? ` as ${status.identity}` : ''}`
+            : 'not connected — run skillshare teams login';
+    return [
+        `Teams: ${state}`,
+        ...fields([
+            ['Access', status.configured ? status.accessMode : undefined],
+            ['Session expires', status.configured && status.expiresAt ? formatDateTime(status.expiresAt) : undefined],
+            ['Updated', status.updatedAt ? formatDateTime(status.updatedAt) : undefined],
+            ['MCP endpoint', status.endpoint],
+        ]),
+    ].join('\n');
+}
+export function pageUrl(baseUrl, slug) {
+    return `${baseUrl.replace(/\/+$/, '')}/p/${encodeURIComponent(slug)}/`;
+}

package/dist/pages.js

@@ -1,7 +1,36 @@
 import { builtinModules } from 'node:module';
 import { build } from 'esbuild';
 import { parse, printParseErrorCode } from 'jsonc-parser';
-import { resolve, relative } from 'node:path';
+import { basename, dirname, resolve, relative } from 'node:path';
+// Build output folders say nothing about the page, so publishing them under their own name is almost always a mistake.
+const GENERIC_DIRECTORY_NAMES = new Set(['dist', 'build', 'out', 'output', 'public', 'www', 'static', 'site', '_site', 'html', 'web', 'export']);
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+export function normalizePageSlug(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!SLUG_PATTERN.test(normalized)) {
+        throw new Error('Page slug must be 1-64 lowercase letters, numbers, or hyphens, and cannot start or end with a hyphen.');
+    }
+    return normalized;
+}
+export function resolvePageSlug(directory, explicitSlug) {
+    if (explicitSlug !== undefined)
+        return normalizePageSlug(explicitSlug);
+    const resolvedDirectory = resolve(directory);
+    const name = basename(resolvedDirectory);
+    if (GENERIC_DIRECTORY_NAMES.has(name.toLowerCase().replace(/^\./, ''))) {
+        const suggestion = toSlugCandidate(basename(dirname(resolvedDirectory)));
+        throw new Error(`'${name}' looks like a build output folder, not a page name. Pass --slug, for example --slug ${suggestion && !GENERIC_DIRECTORY_NAMES.has(suggestion) ? suggestion : 'my-page'}.`);
+    }
+    const candidate = toSlugCandidate(name);
+    if (!candidate) {
+        throw new Error(`Cannot derive a page slug from '${name}'. Pass --slug <slug>.`);
+    }
+    return candidate;
+}
+function toSlugCandidate(value) {
+    const candidate = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64).replace(/-+$/, '');
+    return SLUG_PATTERN.test(candidate) ? candidate : '';
+}
 export async function preparePageFiles(directory, files) {
     const configurations = files.filter(file => file.relativePath === 'wrangler.json' || file.relativePath === 'wrangler.jsonc');
     if (configurations.length > 1)

package/dist/teams-auth.js

@@ -16,7 +16,7 @@ export function decodeTeamsJwt(value) {
 /** Select only credentials belonging to the Skillshare account. No full browser state leaves this machine. */
 export function extractTeamsSession(state, expectedObjectId, now = Date.now(), allowExpired = false) {
     if (!uuid.test(expectedObjectId))
-        throw new Error('Skillshare must be signed in with a Microsoft account before connecting Teams.');
+        throw new Error('The Microsoft account object id is missing. Sign in to Skillshare in the browser, then run skillshare teams login again.');
     const stores = state.origins.filter(origin => origins.has(origin.origin));
     const entries = stores.flatMap(origin => origin.localStorage.flatMap(item => {
         try {

package/dist/teams.js

@@ -6,7 +6,19 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { captureTeamsLogin } from './teams-auth.js';
 import { watchTeamsConnection } from './teams-watch.js';
+import { renderTeamsStatus } from './output.js';
 const root = '/api/mcps/providers/teams';
+const guid = /^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i;
+/**
+ * Skillshare identifies users by the pairwise subject; Teams credentials carry the Entra
+ * object id, which the server records at web sign-in. Older servers only return a GUID id.
+ */
+export function resolveTeamsObjectId(account) {
+    if (account.entraObjectId && guid.test(account.entraObjectId))
+        return account.entraObjectId;
+    return guid.test(account.id) ? account.id : null;
+}
+export const UNLINKED_ACCOUNT_MESSAGE = 'Skillshare does not know your Microsoft account yet. Run "skillshare login" (or open Skillshare in the browser and sign in), then run "skillshare teams login" again.';
 async function expectOk(response) {
     if (response.ok)
         return;
@@ -23,11 +35,15 @@ export async function runTeamsCommand(client, args, flags, appDirectory) {
     const action = args[0];
     if (action === 'login' || action === 'watch') {
         const user = await client.get('/api/auth/me');
+        const resolvedObjectId = resolveTeamsObjectId(user);
+        if (!resolvedObjectId)
+            throw new Error(UNLINKED_ACCOUNT_MESSAGE);
+        const objectId = resolvedObjectId;
         const key = createHash('sha256').update(client.baseUrl + '\0' + user.id).digest('hex').slice(0, 24);
         const profileDirectory = flags['browser-profile'] ? resolve(flags['browser-profile']) : join(appDirectory, 'teams', key, 'browser-profile');
         const abort = new AbortController();
         async function connect(connectionId) {
-            const session = await captureTeamsLogin({ profileDirectory, objectId: user.id, browser: flags.browser,
+            const session = await captureTeamsLogin({ profileDirectory, objectId, browser: flags.browser,
                 headless: action === 'watch' ? flags.headless !== 'false' : flags.headless === 'true', recover: action === 'watch',
                 signal: abort.signal, timeoutMs: action === 'watch' ? 90_000 : undefined, onProgress: console.log });
             const headers = { 'Content-Type': 'application/json' };
@@ -57,9 +73,15 @@ export async function runTeamsCommand(client, args, flags, appDirectory) {
         }
         return;
     }
-    if (action === 'status' || action === 'test') {
-        const result = action === 'test' ? await client.post(`${root}/test`) : await client.get(`${root}/settings`);
-        console.log(JSON.stringify(result, null, 2));
+    const json = flags.json === 'true';
+    if (action === 'status') {
+        const status = await client.get(`${root}/settings`);
+        console.log(json ? JSON.stringify(status, null, 2) : renderTeamsStatus(status));
+        return;
+    }
+    if (action === 'test') {
+        const result = await client.post(`${root}/test`);
+        console.log(json ? JSON.stringify(result, null, 2) : `Teams connection works${result.identity ? ` for ${result.identity}` : ''}.`);
         return;
     }
     if (action === 'logout') {
@@ -92,7 +114,8 @@ export async function runTeamsCommand(client, args, flags, appDirectory) {
                 body: Readable.toWeb(stream), duplex: 'half',
             });
             await expectOk(response);
-            console.log(JSON.stringify(await response.json(), null, 2));
+            const item = await response.json();
+            console.log(json ? JSON.stringify(item, null, 2) : `Uploaded ${item.name ?? basename(path)} to your Teams files.${item.webUrl ? `\n  ${item.webUrl}` : ''}`);
         }
         finally {
             stream.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadient/skillshare",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Skillshare CLI for installing and publishing Quadient skills",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "start": "node ./dist/index.js",
     "prepublishOnly": "npm run build",
-    "test": "tsx --test cli-args.test.ts install-files.test.ts pages.test.ts pages-dev.test.ts teams-auth.test.ts teams-watch.test.ts teams-browser.test.ts"
+    "test": "tsx --test cli-args.test.ts install-files.test.ts output.test.ts pages.test.ts pages-dev.test.ts teams-auth.test.ts teams-watch.test.ts teams-browser.test.ts agents.test.ts"
   },
   "publishConfig": {
     "access": "public"