@quadient/skillshare 1.10.2 → 1.10.3

package/README.md

@@ -40,6 +40,21 @@ skillshare agents listen --workdir ~/Research
 skillshare agents listen --name desktop --max-concurrency 2
 ```
 
+The listener updates itself: when Skillshare releases a newer CLI, it downloads it into
+`~/.config/skillshare/versions` (on Windows `%APPDATA%\skillshare\versions`) and restarts on
+it once no turn is running. `--no-update` turns that off.
+
+To keep it running without a terminal, install it as a background service that starts at
+every login: a launchd agent on macOS, a systemd user service on Linux and a scheduled task
+on Windows. It takes the same options as `listen`; run it again to change them.
+
+```sh
+skillshare agents service install --workdir ~/Research
+skillshare agents service status
+skillshare agents service logs --lines 100
+skillshare agents service uninstall
+```
+
 `--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`.

package/dist/agents-service.js

@@ -0,0 +1,288 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { describeOtherListener, installVersion, readListenerLock, runCommand, } from './agents-update.js';
+export const LAUNCHD_LABEL = 'com.quadient.skillshare.agents';
+export const SYSTEMD_UNIT = 'skillshare-agents.service';
+export const WINDOWS_TASK = 'Skillshare Agents';
+export function defaultServiceEnvironment(appDir) {
+    const platform = process.platform;
+    if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win32')
+        throw new Error(`The agents service is not supported on ${platform}.`);
+    return {
+        appDir, platform, home: homedir(), run: runCommand, uid: process.getuid?.(),
+        windowsUser: process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : process.env.USERNAME,
+    };
+}
+export function servicePaths(appDir) {
+    return {
+        config: join(appDir, 'agents-service.json'),
+        launcher: join(appDir, 'agents-service.mjs'),
+        log: join(appDir, 'logs', 'agents.log'),
+        // What the service manager catches before the listener's own log opens, such as a launcher that cannot start.
+        output: join(appDir, 'logs', 'agents-service.out'),
+        windowsTask: join(appDir, 'agents-service-task.xml'),
+    };
+}
+/** Where the service manager keeps the service definition. */
+export function definitionPath(environment) {
+    switch (environment.platform) {
+        case 'darwin': return join(environment.home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+        case 'linux': return join(process.env.XDG_CONFIG_HOME ?? join(environment.home, '.config'), 'systemd', 'user', SYSTEMD_UNIT);
+        case 'win32': return servicePaths(environment.appDir).windowsTask;
+    }
+}
+/**
+ * The launcher the service manager starts. It does not depend on any CLI version: it picks the newest installed one, so an
+ * update downloaded by the listener also applies after a restart of the computer.
+ */
+export function launcherSource() {
+    return `// Starts the Skillshare agents listener as a background service. Written by skillshare agents service install.
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const appDir = dirname(fileURLToPath(import.meta.url))
+const config = JSON.parse(readFileSync(join(appDir, 'agents-service.json'), 'utf8'))
+const versions = join(appDir, 'versions')
+const parts = (version) => version.split('.').map(Number)
+const compare = (a, b) => { const [x, y] = [parts(a), parts(b)]; return x[0] - y[0] || x[1] - y[1] || x[2] - y[2] }
+const installed = existsSync(versions)
+  ? readdirSync(versions).filter((name) => /^\\d+\\.\\d+\\.\\d+$/.test(name) && existsSync(join(versions, name, '.installed'))).sort(compare)
+  : []
+const version = installed.at(-1)
+if (!version) {
+  console.error('No Skillshare CLI is installed for the agents service. Run skillshare agents service install again.')
+  process.exit(1)
+}
+const entry = join(versions, version, 'node_modules', '@quadient', 'skillshare', 'dist', 'index.js')
+process.env.PATH = config.path
+process.env.SKILLSHARE_AGENTS_SERVICE = '1'
+process.chdir(appDir)
+process.argv = [process.argv[0], entry, 'agents', 'listen', '--server', config.server, '--workdir', config.workdir,
+  '--log-file', join(appDir, 'logs', 'agents.log'), ...config.args]
+await import(pathToFileURL(entry).href)
+`;
+}
+function xml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** A launchd agent in the user's login session, so agents reach the keychain and the browser; started again if it fails. */
+export function launchdPlist(config, appDir) {
+    const paths = servicePaths(appDir);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(config.node)}</string>
+    <string>${xml(paths.launcher)}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(appDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xml(paths.output)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(paths.output)}</string>
+</dict>
+</plist>
+`;
+}
+function systemdQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
+}
+/** A systemd user service, started with the user's session and again whenever it fails. */
+export function systemdUnit(config, appDir) {
+    const paths = servicePaths(appDir);
+    return `[Unit]
+Description=Skillshare agents listener
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${systemdQuote(config.node)} ${systemdQuote(paths.launcher)}
+WorkingDirectory=${systemdQuote(appDir)}
+Restart=on-failure
+RestartSec=30
+StandardOutput=append:${paths.output}
+StandardError=append:${paths.output}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * A scheduled task that starts at logon in the user's session, without a time limit and also on battery. conhost
+ * --headless runs Node without a console window.
+ */
+export function windowsTaskXml(config, appDir, user) {
+    const paths = servicePaths(appDir);
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Skillshare agents listener</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xml(user)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${xml(user)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>conhost.exe</Command>
+      <Arguments>--headless "${xml(config.node)}" "${xml(paths.launcher)}"</Arguments>
+      <WorkingDirectory>${xml(appDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+async function must(environment, command, args, what) {
+    const result = await environment.run(command, args);
+    if (result.code !== 0)
+        throw new Error(`${what} failed: ${(result.stderr || result.stdout).trim() || `exit code ${result.code}`}`);
+    return result;
+}
+/**
+ * Installs the CLI version for the service, writes the launcher and registers it with the service manager, which starts it
+ * now and at every login. Installing again replaces the service, for example with other options.
+ */
+export async function installService(environment, settings, options = {}) {
+    const other = await readListenerLock(environment.appDir);
+    if (other && !other.service)
+        throw new Error(describeOtherListener(other));
+    await (options.install ?? (version => installVersion(environment.appDir, version)))(settings.version);
+    const config = { ...settings, path: process.env.PATH ?? '', node: process.execPath, installedAt: new Date().toISOString() };
+    const paths = servicePaths(environment.appDir);
+    await mkdir(dirname(paths.log), { recursive: true });
+    await writeFile(paths.config, JSON.stringify(config, null, 2));
+    await writeFile(paths.launcher, launcherSource());
+    const definition = definitionPath(environment);
+    await mkdir(dirname(definition), { recursive: true });
+    switch (environment.platform) {
+        case 'darwin': {
+            const domain = `gui/${environment.uid}`;
+            await environment.run('launchctl', ['bootout', `${domain}/${LAUNCHD_LABEL}`]);
+            await writeFile(definition, launchdPlist(config, environment.appDir));
+            await must(environment, 'launchctl', ['bootstrap', domain, definition], 'launchctl bootstrap');
+            break;
+        }
+        case 'linux':
+            await writeFile(definition, systemdUnit(config, environment.appDir));
+            await must(environment, 'systemctl', ['--user', 'daemon-reload'], 'systemctl daemon-reload');
+            await must(environment, 'systemctl', ['--user', 'enable', SYSTEMD_UNIT], 'systemctl enable');
+            await must(environment, 'systemctl', ['--user', 'restart', SYSTEMD_UNIT], 'systemctl restart');
+            break;
+        case 'win32':
+            // schtasks reads task definitions as UTF-16.
+            await writeFile(definition, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(windowsTaskXml(config, environment.appDir, environment.windowsUser ?? ''), 'utf16le')]));
+            await environment.run('schtasks', ['/End', '/TN', WINDOWS_TASK]);
+            await must(environment, 'schtasks', ['/Create', '/TN', WINDOWS_TASK, '/XML', definition, '/F'], 'schtasks /Create');
+            await must(environment, 'schtasks', ['/Run', '/TN', WINDOWS_TASK], 'schtasks /Run');
+            break;
+    }
+    return config;
+}
+/** Stops the service and removes it; downloaded CLI versions and logs stay. */
+export async function uninstallService(environment) {
+    const definition = definitionPath(environment);
+    switch (environment.platform) {
+        case 'darwin':
+            await environment.run('launchctl', ['bootout', `gui/${environment.uid}/${LAUNCHD_LABEL}`]);
+            break;
+        case 'linux':
+            await environment.run('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT]);
+            break;
+        case 'win32':
+            await environment.run('schtasks', ['/End', '/TN', WINDOWS_TASK]);
+            await environment.run('schtasks', ['/Delete', '/TN', WINDOWS_TASK, '/F']);
+            break;
+    }
+    const existed = existsSync(definition) || existsSync(servicePaths(environment.appDir).config);
+    const paths = servicePaths(environment.appDir);
+    for (const path of [definition, paths.config, paths.launcher])
+        await rm(path, { force: true });
+    if (environment.platform === 'linux')
+        await environment.run('systemctl', ['--user', 'daemon-reload']);
+    return existed;
+}
+export async function serviceStatus(environment) {
+    let config;
+    try {
+        config = JSON.parse(await readFile(servicePaths(environment.appDir).config, 'utf8'));
+    }
+    catch { }
+    const lock = await readListenerLock(environment.appDir);
+    const running = lock?.service === true;
+    return {
+        installed: config !== undefined && existsSync(definitionPath(environment)), config, running,
+        pid: running ? lock.pid : undefined, version: running ? lock.version : undefined, since: running ? lock.startedAt : undefined,
+    };
+}
+export function renderServiceStatus(status, appDir) {
+    if (!status.installed)
+        return 'The agents service is not installed. Install it with skillshare agents service install.';
+    const lines = [
+        status.running
+            ? `The agents service is running (process ${status.pid}, Skillshare CLI ${status.version}, since ${status.since}).`
+            : 'The agents service is installed but not running. See skillshare agents service logs.',
+        `Server: ${status.config.server}`,
+        `Working directory: ${status.config.workdir}`,
+    ];
+    if (status.config.args.length)
+        lines.push(`Options: ${status.config.args.join(' ')}`);
+    lines.push(`Log: ${servicePaths(appDir).log}`);
+    return lines.join('\n');
+}
+/** The end of the listener's log, and of the service manager's output when the listener could not start. */
+export async function serviceLogs(appDir, lines) {
+    const paths = servicePaths(appDir);
+    const tail = async (path) => {
+        try {
+            return (await readFile(path, 'utf8')).trimEnd().split('\n').slice(-lines).join('\n');
+        }
+        catch {
+            return '';
+        }
+    };
+    const [log, output] = [await tail(paths.log), await tail(paths.output)];
+    return [log, output ? `--- ${paths.output}\n${output}` : ''].filter(Boolean).join('\n') || 'The agents service has not written a log yet.';
+}

package/dist/agents-session.js

@@ -135,6 +135,8 @@ export class SessionRunner {
         });
     }
     get stopping() { return this.closing !== null; }
+    /** A turn runs or a message waits for one; restarting the listener now would cut it off. */
+    get busy() { return this.turnRunning || this.steering.size > 0 || this.pending.length > 0; }
     /**
      * Queues messages for the next turns, or steers them into the running turn; the server may send a message again, so
      * repeats are ignored.

package/dist/agents-update.js

@@ -0,0 +1,254 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+export const PACKAGE_NAME = '@quadient/skillshare';
+/** A listener exits with this code to be started again on the newest installed CLI. */
+export const RESTART_FOR_UPDATE = 75;
+/** Set for the listener the supervisor runs, so it listens instead of supervising again. */
+export const WORKER_ENV = 'SKILLSHARE_AGENTS_WORKER';
+/** Set when the listener runs as a background service, where nobody can answer a browser sign-in. */
+export const SERVICE_ENV = 'SKILLSHARE_AGENTS_SERVICE';
+const INSTALLED_MARKER = '.installed';
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+// A listener that fails this soon after its first start has a problem a restart will not fix, such as a bad option.
+const EARLY_FAILURE_MS = 30_000;
+/** Compares x.y.z versions numerically; anything after - or + is ignored. */
+export function compareVersions(a, b) {
+    const parse = (version) => version.split(/[-+]/)[0].split('.').map(part => Number(part) || 0);
+    const [left, right] = [parse(a), parse(b)];
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return 0;
+}
+export function versionsDirectory(appDir) {
+    return join(appDir, 'versions');
+}
+/** The CLI entry point of an installed version. */
+export function versionEntry(appDir, version) {
+    return join(versionsDirectory(appDir), version, 'node_modules', '@quadient', 'skillshare', 'dist', 'index.js');
+}
+/** Completely installed versions, oldest first. */
+export async function installedVersions(appDir) {
+    let names = [];
+    try {
+        names = await readdir(versionsDirectory(appDir));
+    }
+    catch {
+        return [];
+    }
+    return names.filter(name => /^\d+\.\d+\.\d+$/.test(name) && existsSync(join(versionsDirectory(appDir), name, INSTALLED_MARKER)))
+        .sort(compareVersions);
+}
+/** Runs a command without a shell, except for Windows .cmd scripts, which Node only starts through one. */
+export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const shell = process.platform === 'win32' && /\.cmd$/i.test(command);
+    const child = spawn(shell ? quoteForCmd(command) : command, shell ? args.map(quoteForCmd) : args, { cwd: options.cwd, shell, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', code => resolve({ code: code ?? 1, stdout, stderr }));
+});
+function quoteForCmd(value) {
+    return /[\s"&|<>^]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+/** npm next to the running Node, so a service with a bare PATH still finds it; otherwise npm on PATH. */
+export function npmCommand() {
+    const bin = dirname(process.execPath);
+    for (const cli of [join(bin, 'node_modules', 'npm', 'bin', 'npm-cli.js'), join(bin, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')])
+        if (existsSync(cli))
+            return { command: process.execPath, args: [cli] };
+    return { command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: [] };
+}
+/**
+ * Installs a CLI version into its own directory under versions, without touching a global install, so no administrator
+ * rights are needed. It lands under a temporary name first, so a listener never starts a half-installed version.
+ */
+export async function installVersion(appDir, version, options = {}) {
+    if ((await installedVersions(appDir)).includes(version))
+        return;
+    const target = join(versionsDirectory(appDir), version);
+    const staging = `${target}.partial-${process.pid}`;
+    await rm(staging, { recursive: true, force: true });
+    await mkdir(staging, { recursive: true });
+    try {
+        // An empty project of its own keeps npm from installing into a parent directory's project.
+        await writeFile(join(staging, 'package.json'), JSON.stringify({ private: true }));
+        const npm = npmCommand();
+        const result = await (options.run ?? runCommand)(npm.command, [...npm.args, 'install', '--prefix', staging, '--no-audit', '--no-fund',
+            '--omit=dev', '--no-package-lock', options.spec ?? `${PACKAGE_NAME}@${version}`], { cwd: staging });
+        if (result.code !== 0)
+            throw new Error(`npm could not install ${PACKAGE_NAME}@${version}: ${lastLine(result.stderr) || `exit code ${result.code}`}`);
+        const installed = join(staging, 'node_modules', '@quadient', 'skillshare');
+        const actual = JSON.parse(await readFile(join(installed, 'package.json'), 'utf8'));
+        if (actual.version !== version)
+            throw new Error(`npm installed ${PACKAGE_NAME}@${actual.version ?? '?'} instead of ${version}.`);
+        await writeFile(join(staging, INSTALLED_MARKER), version);
+        await rm(target, { recursive: true, force: true });
+        await rename(staging, target);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}
+function lastLine(text) {
+    return text.trim().split('\n').filter(line => line.trim()).at(-1)?.trim() ?? '';
+}
+/** Removes installed versions other than the ones kept, and leftovers of interrupted installs. */
+export async function removeOtherVersions(appDir, keep) {
+    let names = [];
+    try {
+        names = await readdir(versionsDirectory(appDir));
+    }
+    catch {
+        return;
+    }
+    for (const name of names)
+        if (!keep.includes(name))
+            await rm(join(versionsDirectory(appDir), name), { recursive: true, force: true }).catch(() => { });
+}
+/** Appends timestamped lines to a log file, starting a new one when it grows past a few megabytes. */
+export function fileLog(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    return (text) => {
+        try {
+            if (existsSync(path) && statSync(path).size > MAX_LOG_BYTES)
+                renameSync(path, `${path}.1`);
+            const stamp = new Date().toISOString();
+            appendFileSync(path, text.split(/\r?\n/).filter(line => line.length > 0).map(line => `${stamp} ${line}\n`).join(''));
+        }
+        catch {
+            // Logging must never stop the listener.
+        }
+    };
+}
+/** Where a supervisor that holds the listener records itself, so a second one does not poll as the same listener. */
+export function listenerLockPath(appDir) {
+    return join(appDir, 'agents-listener.json');
+}
+export async function readListenerLock(appDir) {
+    try {
+        const lock = JSON.parse(await readFile(listenerLockPath(appDir), 'utf8'));
+        return isAlive(lock.pid) ? lock : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Records this process as the one listening; returns the other listener instead when one is already running. */
+export async function acquireListenerLock(appDir, lock) {
+    const existing = await readListenerLock(appDir);
+    if (existing && existing.pid !== process.pid)
+        return existing;
+    await mkdir(appDir, { recursive: true });
+    await writeFile(listenerLockPath(appDir), JSON.stringify({ ...lock, pid: process.pid, startedAt: new Date().toISOString() }, null, 2));
+    return null;
+}
+export async function releaseListenerLock(appDir) {
+    const lock = await readListenerLock(appDir);
+    if (lock?.pid === process.pid)
+        await rm(listenerLockPath(appDir), { force: true }).catch(() => { });
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Keeps a listener running on the newest installed CLI. The listener downloads a new version the server announces and
+ * exits with RESTART_FOR_UPDATE once no turn is running; the supervisor then starts the new version. A listener that
+ * crashes later is restarted with a growing pause; one that fails right after its first start ends the supervisor with its
+ * exit code, because the problem is in how it was started.
+ */
+export async function superviseListener(options) {
+    const write = options.logFile ? fileLog(options.logFile) : undefined;
+    const log = options.log ?? ((message) => write ? write(message) : console.log(message));
+    const existing = await acquireListenerLock(options.appDir, { version: options.ownVersion, service: options.service === true });
+    if (existing) {
+        log(describeOtherListener(existing));
+        return 1;
+    }
+    let child = null;
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        // In a terminal, Ctrl+C reaches the listener directly; elsewhere it is told here. Windows cannot signal gracefully.
+        if (child && process.platform !== 'win32')
+            child.kill('SIGTERM');
+        if (child)
+            setTimeout(() => child?.kill('SIGKILL'), 30_000).unref();
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    options.signal?.addEventListener('abort', stop, { once: true });
+    let failures = 0;
+    let first = true;
+    try {
+        while (!stopping) {
+            const newest = (await installedVersions(options.appDir)).at(-1);
+            const useInstalled = newest !== undefined && compareVersions(newest, options.ownVersion) > 0;
+            const version = useInstalled ? newest : options.ownVersion;
+            const entry = useInstalled ? [versionEntry(options.appDir, newest)] : options.ownEntry ?? [...process.execArgv, process.argv[1]];
+            // Older versions are not needed any more; this CLI's own copy stays while it runs.
+            await removeOtherVersions(options.appDir, [version, options.ownVersion]);
+            log(`Starting the listener with Skillshare CLI ${version}.`);
+            await acquireListenerLock(options.appDir, { version, service: options.service === true });
+            const startedAt = Date.now();
+            child = spawn(process.execPath, [...entry, ...options.args], {
+                env: { ...process.env, [WORKER_ENV]: '1', ...(options.service ? { [SERVICE_ENV]: '1' } : {}) },
+                stdio: write ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+                windowsHide: true,
+            });
+            if (write) {
+                child.stdout?.on('data', chunk => write(String(chunk)));
+                child.stderr?.on('data', chunk => write(String(chunk)));
+            }
+            const code = await new Promise(resolve => {
+                child.on('error', () => resolve(1));
+                child.on('exit', (exitCode, signal) => resolve(exitCode ?? (signal ? 128 : 1)));
+            });
+            child = null;
+            if (stopping)
+                return 0;
+            if (code === RESTART_FOR_UPDATE) {
+                failures = 0;
+                first = false;
+                continue;
+            }
+            if (code === 0)
+                return 0;
+            if (first && Date.now() - startedAt < EARLY_FAILURE_MS)
+                return code;
+            first = false;
+            failures = Date.now() - startedAt > 10 * 60_000 ? 1 : failures + 1;
+            const pause = Math.min(5 * 60_000, 5000 * 2 ** (failures - 1));
+            log(`The listener stopped with exit code ${code}; starting it again in ${Math.round(pause / 1000)} s.`);
+            await delay(pause, undefined, { signal: options.signal }).catch(() => { });
+        }
+        return 0;
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        await releaseListenerLock(options.appDir);
+    }
+}
+export function describeOtherListener(lock) {
+    return lock.service
+        ? `The Skillshare agents service already listens on this computer (process ${lock.pid}). Stop it with skillshare agents service uninstall, or leave it running.`
+        : `Another skillshare agents listen already runs on this computer (process ${lock.pid}). Stop it first; both would answer as the same listener.`;
+}

package/dist/agents.js

@@ -4,9 +4,11 @@ import { hostname, platform, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { createClaudeDriver } from './agents-claude.js';
+import { defaultServiceEnvironment, installService, renderServiceStatus, serviceLogs, serviceStatus, uninstallService, } from './agents-service.js';
 import { createCodexDriver } from './agents-codex.js';
 import { detectAgents, profilesPath } from './agents-detect.js';
 import { SessionRunner, errorMessage, } from './agents-session.js';
+import { RESTART_FOR_UPDATE, SERVICE_ENV, WORKER_ENV, acquireListenerLock, compareVersions, describeOtherListener, installVersion, releaseListenerLock, superviseListener, } from './agents-update.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.';
@@ -92,19 +94,34 @@ export async function runAgentsCommand(client, args, flags, appDirectory, teamsW
         console.log(renderDetected(listenerId, client.baseUrl, detected));
         return;
     }
+    if (action === 'service')
+        return runServiceCommand(args[1], flags, appDirectory, client.baseUrl);
     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.');
+        throw new Error('agents requires listen, status or service.');
+    const max = maxConcurrency(flags);
+    const worker = process.env[WORKER_ENV] === '1';
+    const service = process.env[SERVICE_ENV] === '1';
+    // The listener runs under a supervisor that starts it again on a newer CLI, unless updates are turned off.
+    if (!worker && flags['no-update'] !== 'true') {
+        const code = await superviseListener({ appDir: appDirectory, args: process.argv.slice(2), ownVersion: readCliVersion(), logFile: flags['log-file'], service });
+        if (code !== 0)
+            process.exitCode = code;
+        return;
+    }
+    if (!worker) {
+        const other = await acquireListenerLock(appDirectory, { version: readCliVersion(), service });
+        if (other)
+            throw new Error(describeOtherListener(other));
+    }
     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();
+    // A supervisor may pass on a signal the listener already got from the terminal; stopping twice is harmless.
     const stop = () => abort.abort();
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    process.on('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.');
@@ -114,14 +131,82 @@ export async function runAgentsCommand(client, args, flags, appDirectory, teamsW
         ? teamsWatch(abort.signal, message => console.log(`[teams] ${message}`))
             .catch(error => console.log(`[teams] Teams renewal stopped: ${error instanceof Error ? error.message : String(error)}`))
         : Promise.resolve();
+    let result = 'stopped';
     try {
-        await listen({ client, listenerId, name: flags.name, workdir, maxConcurrency: max, sandbox, signal: abort.signal, onProgress: console.log });
+        result = await listen({
+            client, listenerId, name: flags.name, workdir, maxConcurrency: max, sandbox, signal: abort.signal, onProgress: console.log, service,
+            updater: worker ? { currentVersion: readCliVersion(), prepare: version => installVersion(appDirectory, version) } : undefined,
+        });
     }
     finally {
         abort.abort();
         await teams;
         process.removeListener('SIGINT', stop);
         process.removeListener('SIGTERM', stop);
+        if (!worker)
+            await releaseListenerLock(appDirectory);
+    }
+    if (result === 'update') {
+        process.exitCode = RESTART_FOR_UPDATE;
+        // Nothing may keep the old version alive; the supervisor waits for this process to end.
+        setTimeout(() => process.exit(RESTART_FOR_UPDATE), 5000).unref();
+    }
+}
+function maxConcurrency(flags) {
+    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.');
+    return max;
+}
+/** Listen options a service keeps; the server and the working directory are stored on their own. */
+export function serviceListenArgs(flags) {
+    const args = [];
+    for (const key of ['name', 'max-concurrency', 'browser', 'browser-profile'])
+        if (flags[key] !== undefined)
+            args.push(`--${key}`, flags[key]);
+    for (const key of ['sandbox', 'no-teams-watch', 'headless'])
+        if (flags[key] === 'true')
+            args.push(`--${key}`);
+    return args;
+}
+/** install needs the server, so it runs after sign-in; the other actions work offline. */
+export async function runServiceCommand(action, flags, appDirectory, server) {
+    const environment = defaultServiceEnvironment(appDirectory);
+    switch (action) {
+        case 'install': {
+            if (!server)
+                throw new Error('agents service install needs a Skillshare server.');
+            maxConcurrency(flags);
+            const workdir = resolve(flags.workdir ?? process.cwd());
+            const version = readCliVersion();
+            console.log(`Installing Skillshare CLI ${version} for the agents service…`);
+            await installService(environment, { server, workdir, args: serviceListenArgs(flags), version });
+            // The service manager starts it right away; it takes a moment to sign in and report.
+            let status = await serviceStatus(environment);
+            for (let attempt = 0; attempt < 30 && !status.running; attempt++) {
+                await delay(500);
+                status = await serviceStatus(environment);
+            }
+            console.log(renderServiceStatus(status, appDirectory));
+            console.log('It starts at every login and updates itself when Skillshare releases a new CLI.' +
+                (environment.platform === 'linux' ? ' To keep it running after you log out, run loginctl enable-linger.' : ''));
+            return;
+        }
+        case 'uninstall':
+            console.log(await uninstallService(environment) ? 'The agents service was removed.' : 'The agents service was not installed.');
+            return;
+        case 'status':
+            console.log(renderServiceStatus(await serviceStatus(environment), appDirectory));
+            return;
+        case 'logs': {
+            const lines = flags.lines === undefined ? 50 : Number(flags.lines);
+            if (!Number.isInteger(lines) || lines < 1)
+                throw new Error('--lines must be a positive number.');
+            console.log(await serviceLogs(appDirectory, lines));
+            return;
+        }
+        default:
+            throw new Error('agents service requires install, uninstall, status or logs.');
     }
 }
 export function renderDetected(listenerId, server, detected) {
@@ -159,12 +244,40 @@ export async function listen(options) {
     let registeredFingerprint = '';
     let detectedAt = now();
     let failures = 0;
+    // A downloaded update waits until no turn runs; a failed download is tried again later.
+    let updateReady = null;
+    let updating = null;
+    let updateRetryAt = 0;
+    let updateMentioned = '';
+    let result = 'stopped';
+    function considerUpdate(version) {
+        const current = options.updater?.currentVersion ?? readCliVersion();
+        if (!version || compareVersions(version, current) <= 0 || updateReady === version || updating === version)
+            return;
+        if (!options.updater) {
+            if (updateMentioned !== version)
+                log(`Skillshare CLI ${version} is available. Update with npm install -g @quadient/skillshare@${version}.`);
+            updateMentioned = version;
+            return;
+        }
+        if (now() < updateRetryAt)
+            return;
+        updating = version;
+        log(`Downloading Skillshare CLI ${version}…`);
+        options.updater.prepare(version).then(() => {
+            updateReady = version;
+            log(`Skillshare CLI ${version} is ready; the listener restarts with it once no turn is running.`);
+        }).catch(error => {
+            updateRetryAt = now() + 30 * 60_000;
+            log(`! Could not download Skillshare CLI ${version} (${error instanceof Error ? error.message : String(error)}). Trying again in 30 minutes.`);
+        }).finally(() => { updating = null; });
+    }
     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(),
+            capabilities: capabilities(), service: options.service === true, autoUpdate: options.updater !== undefined,
         }, options.signal);
         registeredFingerprint = fingerprint;
         for (const problem of detected.problems)
@@ -232,6 +345,11 @@ export async function listen(options) {
     }
     try {
         while (!options.signal.aborted) {
+            if (updateReady && ![...sessions.values()].some(runner => runner.busy)) {
+                log(`Restarting with Skillshare CLI ${updateReady}.`);
+                result = 'update';
+                break;
+            }
             try {
                 if (now() - detectedAt > (options.redetectMs ?? 5 * 60_000)) {
                     detected = await detect();
@@ -248,6 +366,7 @@ export async function listen(options) {
                 failures = 0;
                 for (const command of response.commands)
                     handle(command);
+                considerUpdate(response.cliVersion);
                 if (response.commands.length === 0 && now() - polledAt < 1000)
                     await wait(1000, options.signal).catch(() => { });
             }
@@ -274,6 +393,7 @@ export async function listen(options) {
         // Closing reports each session as closed, so the server knows at once that the next message must resume it.
         await Promise.all([...sessions.values()].map(runner => runner.close()));
     }
+    return result;
 }
 function label(start) {
     const { configuration } = start;

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', 'json', 'no-teams-watch', 'sandbox']);
+export const BOOLEAN_FLAGS = new Set(['dry-run', 'force', 'headless', 'help', 'json', 'no-teams-watch', 'no-update', 'sandbox']);
 export const COMMANDS = [
     {
         name: 'login',
@@ -112,12 +112,14 @@ export const COMMANDS = [
         name: 'agents',
         summary: 'Run Claude Code or Codex sessions from Skillshare on this computer',
         usage: [
-            'agents listen [local] [--name <name>] [--workdir <directory>] [--max-concurrency <1-4>] [--sandbox] [--no-teams-watch]',
+            'agents listen [local] [--name <name>] [--workdir <directory>] [--max-concurrency <1-4>] [--sandbox] [--no-teams-watch] [--no-update]',
             'agents status [local] [--json]',
+            'agents service install [local] [--name <name>] [--workdir <directory>] [--max-concurrency <1-4>] [--sandbox] [--no-teams-watch]',
+            'agents service status | logs [--lines <n>] | uninstall',
         ],
-        description: 'A listener reports the installed agents, their models and reasoning levels, and the local profiles from ~/.config/skillshare/agents.json. It runs Claude Code and Codex sessions that you start and continue under Sessions in Skillshare; under Connected agents you choose which listener and configuration runs Teams 👀 sessions. Agents use your own login and run with your full local permissions, without permission prompts, unless --sandbox (or "sandbox": true in a profile) keeps them read-only. An idle agent is stopped after 15 minutes and resumed by the next message. With a Teams connection, the listener also keeps the Teams session renewed through local browser SSO, as skillshare teams watch does; --no-teams-watch turns that off.',
-        examples: ['skillshare agents status', 'skillshare agents listen --workdir ~/Research'],
-        flags: ['name', 'workdir', 'max-concurrency', 'sandbox', 'no-teams-watch', 'browser', 'headless', 'browser-profile', 'json'],
+        description: 'A listener reports the installed agents, their models and reasoning levels, and the local profiles from ~/.config/skillshare/agents.json. It runs Claude Code and Codex sessions that you start and continue under Sessions in Skillshare; under Connected agents you choose which listener and configuration runs Teams 👀 sessions. Agents use your own login and run with your full local permissions, without permission prompts, unless --sandbox (or "sandbox": true in a profile) keeps them read-only. An idle agent is stopped after 15 minutes and resumed by the next message. With a Teams connection, the listener also keeps the Teams session renewed through local browser SSO, as skillshare teams watch does; --no-teams-watch turns that off. The listener updates itself: when Skillshare releases a newer CLI, it downloads it and restarts on it once no turn is running (--no-update turns that off). agents service install runs the listener in the background, started at every login (a launchd agent on macOS, a systemd user service on Linux, a scheduled task on Windows); status, logs and uninstall manage it.',
+        examples: ['skillshare agents status', 'skillshare agents listen --workdir ~/Research', 'skillshare agents service install --workdir ~/Research'],
+        flags: ['name', 'workdir', 'max-concurrency', 'sandbox', 'no-teams-watch', 'no-update', 'log-file', 'lines', 'browser', 'headless', 'browser-profile', 'json'],
     },
     {
         name: 'git',

package/dist/index.js

@@ -1,5 +1,6 @@
 import { assertCredentialDestination, resolveTeamsObjectId, runTeamsCommand, watchTeamsInBackground } from './teams.js';
-import { runAgentsCommand } from './agents.js';
+import { runAgentsCommand, runServiceCommand } from './agents.js';
+import { SERVICE_ENV } from './agents-update.js';
 import { formatUnknownCommand, parseCliArgs } from './cli-args.js';
 import { findCommand, readCliVersion, renderCommandHelp, renderUsage } from './help.js';
 import { inspectInstallTarget, installFilesAtomically } from './install-files.js';
@@ -145,10 +146,19 @@ async function main() {
             return;
         }
         case 'agents': {
-            const baseUrl = options.flags.server ?? (options.positionals[1] === 'local' ? LOCAL_URL : await resolveActiveBaseUrl());
+            // Managing the background service needs no server, except to install it.
+            if (options.positionals[0] === 'service' && options.positionals[1] !== 'install') {
+                await runServiceCommand(options.positionals[1], options.flags, APP_DIR);
+                return;
+            }
+            const baseUrl = options.flags.server ?? (options.positionals.slice(1).includes('local') ? LOCAL_URL : await resolveActiveBaseUrl());
             assertCredentialDestination(baseUrl);
-            if (!options.token && !await loadSession(baseUrl))
+            if (!options.token && !await loadSession(baseUrl)) {
+                // A background service has nobody to finish a browser sign-in.
+                if (process.env[SERVICE_ENV] === '1')
+                    throw new Error(`Not signed in to ${baseUrl}. Run skillshare login, then skillshare agents service install again.`);
                 await login(baseUrl);
+            }
             const agentsClient = await createClient(baseUrl, options.token);
             await runAgentsCommand(agentsClient, options.positionals, options.flags, APP_DIR, (signal, log) => watchTeamsInBackground(agentsClient, options.flags, APP_DIR, signal, log));
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadient/skillshare",
-  "version": "1.10.2",
+  "version": "1.10.3",
   "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 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"
+    "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 agents-update.test.ts"
   },
   "publishConfig": {
     "access": "public"