sideby 0.16.0 → 0.17.0

package/dist/src/cli/json-schemas.js

@@ -351,6 +351,9 @@ export const OUTPUT_SCHEMAS = {
         blocked: Type.Optional(Type.String({ description: 'Why the switch cannot run, with what to do.' })),
         message: Type.Optional(Str),
         restartedPanel: Type.Optional(Type.Boolean()),
+        skillSynced: Type.Optional(Type.Boolean({
+            description: 'Back on npm, `sideby update --yes` brought the sideby skill to that version (true) or failed (false).',
+        })),
     }, { title: 'sideby local --json' }),
     list: Type.Object({
         schemaVersion: Version,
@@ -706,6 +709,9 @@ export const OUTPUT_SCHEMAS = {
         refreshedApp: Type.Optional(Type.Boolean({
             description: 'The desktop app (`sideby app install`) was installed and was written again by the new version.',
         })),
+        refreshedAutostart: Type.Optional(Type.Boolean({
+            description: 'A login item (`sideby autostart on`) was installed and now starts the new version (false: that failed). Absent without one.',
+        })),
         skill: Type.Optional(Type.String({ description: 'The command that installs the sideby skill by hand.' })),
         skillUpdate: Type.Optional(Type.Object({
             installed: Type.Array(Type.Union([Str, Type.Null()]), {
@@ -736,6 +742,115 @@ export const OUTPUT_SCHEMAS = {
             description: '`usage` for a malformed command line (exit 2), a reason such as `no-quota-source` or `alias-invalid`, or `error`.',
         }),
     }, { title: 'sideby error --json' }),
+    ask: Type.Object({
+        schemaVersion: Version,
+        task: Type.Union([Str, Type.Null()]),
+        account: Type.Union([Str, Type.Null()]),
+        terminal: Type.Union([Str, Type.Null()]),
+        opened: Type.Boolean(),
+        command: Type.Union([Str, Type.Null()]),
+        removedSecrets: Type.Boolean(),
+        reason: Type.Optional(Type.String({
+            enum: [
+                'no-accounts',
+                'none-signed-in',
+                'all-full',
+                'not-installed',
+                'automation-denied',
+                'npx-cache',
+                'unsafe-path',
+                'failed',
+                'unsupported-platform',
+            ],
+            description: 'Why nothing opened (only when `opened` is false); `detail` says what to do next.',
+        })),
+        detail: Type.Optional(Type.String({ description: 'What to do next, for a person.' })),
+        prompt: Type.Optional(Str),
+        attachments: Type.Array(Type.Object({
+            path: Type.String({ description: 'Absolute path of the copy saved for the task.' }),
+            kind: Type.String({ enum: ['image', 'video'] }),
+            bytes: Type.Integer({ minimum: 0 }),
+        }), { description: 'Files given with `--attach`, in order; empty without any.' }),
+    }),
+    terminal: Type.Object({
+        schemaVersion: Version,
+        preferred: Type.Union([Str, Type.Null()]),
+        guess: Type.Object({ id: Str, source: Type.String({ enum: ['config', 'env', 'default'] }) }),
+        installed: Type.Array(Type.Object({ id: Str, appPath: Type.Optional(Str), executable: Type.Optional(Str) })),
+        terminals: Type.Array(Type.Object({ id: Str, name: Str, installed: Type.Boolean() })),
+    }),
+    key: Type.Object({
+        schemaVersion: Version,
+        account: Str,
+        var: Str,
+        written: Type.Literal(true),
+        path: Str,
+    }),
+    try: Type.Object({
+        schemaVersion: Version,
+        account: Str,
+        confirmed: Type.Boolean(),
+        command: Type.Optional(Type.Array(Str)),
+        ok: Type.Optional(Type.Boolean()),
+        exitCode: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
+        output: Type.Optional(Str),
+        timedOut: Type.Optional(Type.Boolean()),
+    }),
+    'plugins-new': Type.Object({ schemaVersion: Version, dir: Str, files: Type.Array(Str) }),
+    'plugins-check': Type.Object({
+        schemaVersion: Version,
+        ok: Type.Boolean(),
+        plugin: Type.Optional(Str),
+        families: Type.Array(Str),
+        problems: Type.Array(Type.Object({ code: Str, message: Str, fix: Str })),
+    }),
+    autostart: Type.Object({
+        schemaVersion: Version,
+        supported: Type.Boolean({
+            description: 'False on a system sideby cannot start at login yet; `reason` says so.',
+        }),
+        reason: Type.Optional(Str),
+        state: Type.Union(['off', 'on', 'stale', 'foreign'].map((k) => Type.Literal(k)), {
+            description: '`stale`: the Node or sideby it starts no longer exists; `foreign`: a file at that path that sideby did not write.',
+        }),
+        path: Str,
+        programArguments: Type.Optional(Type.Array(Str)),
+        current: Type.Boolean({ description: 'The login item starts this sideby with this Node.' }),
+        missing: Type.Optional(Type.Array(Str)),
+        action: Type.Optional(Type.Union([Type.Literal('on'), Type.Literal('off')])),
+        changed: Type.Optional(Type.Boolean()),
+        applied: Type.Optional(Type.Boolean()),
+        content: Type.Optional(Type.String({ description: 'The file `on` writes.' })),
+        commands: Type.Optional(Type.Array(Type.Array(Str))),
+        loaded: Type.Optional(Type.Boolean({ description: 'launchd took the change now.' })),
+        note: Type.Optional(Str),
+    }),
+    'config-get': Type.Object({
+        schemaVersion: Version,
+        file: Type.Optional(Str),
+        keys: Type.Optional(Type.Array(Type.Object({
+            key: Type.String({ description: 'Dot path; `<…>` marks a part you fill in.' }),
+            meaning: Str,
+            takes: Str,
+            value: Type.Optional(Type.Unknown()),
+            entries: Type.Optional(Type.Array(Type.Object({ key: Str, value: Type.Unknown() }))),
+        }))),
+        key: Type.Optional(Str),
+        set: Type.Optional(Type.Boolean()),
+        value: Type.Optional(Type.Unknown()),
+        meaning: Type.Optional(Str),
+        takes: Type.Optional(Str),
+    }),
+    'config-set': Type.Object({
+        schemaVersion: Version,
+        action: Type.Union([Type.Literal('set'), Type.Literal('unset')]),
+        key: Str,
+        file: Str,
+        changed: Type.Boolean(),
+        applied: Type.Boolean(),
+        before: Type.Optional(Type.Unknown()),
+        after: Type.Optional(Type.Unknown()),
+    }),
     config: ConfigSchema,
 };
 for (const [name, schema] of Object.entries(OUTPUT_SCHEMAS)) {

package/dist/src/cli/main.js

@@ -7,6 +7,10 @@ const MIN_NODE = [22, 18];
 const HELP = `sideby — run every AI coding account side by side
 
 Usage:
+  sideby ask [<text>] [--print]       let your AI handle a sideby task
+  sideby terminal [--set <id>|--custom <t>|--unset] choose your terminal
+  sideby key <account> [--var <NAME>] enter an API key without echo
+  sideby try <account> [--yes]        try the Host with a short paid request
   sideby                              list accounts (same as \`sideby list\`)
   sideby run <account> [-- args]      start the host CLI for one account
   sideby new <family> <name>|--next [--api] [--alias <short>]
@@ -71,14 +75,24 @@ Usage:
   sideby shell-init [zsh|bash] --write
                                       rewrite the config's shellInitFile with them
   sideby plugins                      list loaded plugins and load errors
+  sideby plugins new <id>             create a local Family Plugin skeleton
+  sideby plugins check <id|path>      check a plugin and show fixes
   sideby update [--yes]               update sideby to the newest version (shows the command first)
+  sideby autostart [on|off] [--yes]   start the panel in the background at login (macOS; shows the
+                                      file first)
+  sideby config get [<key>]           every setting with its value and meaning, or one setting
+  sideby config set <key> <value> [--yes]
+                                      change any setting (sideby config set panel.theme dark)
+  sideby config unset <key> [--yes]   back to the default
   sideby local [on|off] [--yes]       for sideby developers: switch the global sideby between the
                                       last local build (pnpm local) and the npm package
 
 Options:
   --json        machine-readable output (list, new, next, alias, doctor, quota, tune, model, remote-control, handoff,
-                families, plugins, app, desktop, browser, update, local)
-  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop, browser
+                families, plugins, app, desktop, browser, update, local, ask, terminal, key, try,
+                autostart, config)
+  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop, browser,
+                autostart, config
   -v, --version show the version
 
 An <account> is <family>:<name> (claude:work) or just <name> when it is unique.
@@ -95,6 +109,11 @@ Updates: once a day sideby asks the npm registry for its newest version and says
   Turn it off with NO_UPDATE_NOTIFIER=1 or config "update": { "check": false }; "auto": true installs by itself.`;
 /** `sideby <command> --help` for the commands agents use to set up and repair accounts (spec §3.16). */
 const COMMAND_HELP = {
+    ask: 'sideby ask [<text>] [--task free|fix|quota|account|host|plugin|terminal|handoff] [--account <ref>] [--terminal <id>] [--attach <file>]... [--print] [--json]\nsideby ask --run <id> [--state-dir <dir>]\nOpen a task in your terminal. --attach adds an image (PNG, JPEG, GIF, WebP; up to 20 MB) or a video (MP4, MOV, WebM; up to 200 MB), at most 5. --print prints only the prompt. If opening fails, paste the command into a terminal.',
+    terminal: "sideby terminal [--set <id>|--custom '<program> … {cwd} … {cmd}'|--unset] [--json]\nList terminals or save your preference; --custom saves and selects your own launch command.",
+    key: 'sideby key <account> [--var <NAME>] [--json]\nEnter an API key without echo. Run in a terminal or use the Panel key box.',
+    try: 'sideby try <account> [--yes] [--json]\nSend a short request through the Host. This spends a few tokens. Exit 10 waits for --yes.',
+    plugins: 'sideby plugins [--json]\nsideby plugins new <id> [--json]\nsideby plugins check <id|path> [--json]\nPlugins run as you, with your permissions. Only load plugins you trust.',
     new: `sideby new <family> <name> [--api] [--alias <short>] [--json]
 sideby new <family> --next [--api] [--alias <short>] [--json]
 
@@ -179,6 +198,42 @@ Examples:
   sideby desktop grok-bot:002 --remove --yes
 Exit: 0 opened, brought to the front or removed; 1 not macOS, no desktop app for that host, API account, app not
 installed, a bad window name, or the app did not open; 10 --remove without --yes; 2 malformed command line.`,
+    autostart: `sideby autostart [on|off] [--yes] [--json]
+
+Start the panel in the background when you log in, so it already shows fresh quota when you open it. It never
+opens a window or a browser and never starts a host. macOS only for now (a LaunchAgent,
+~/Library/LaunchAgents/dev.sideby.panel.plist, that starts this Node and this sideby with ui --background).
+
+Without on or off it says whether it is on, off, out of date (the Node or sideby it starts was moved) or blocked
+by a file that is not sideby's. on and off show the file and the launchctl command first; --yes does it.
+\`sideby update\` and \`pnpm local\` keep an existing login item pointing at the sideby in use.
+
+Examples:
+  sideby autostart --json
+  sideby autostart on --yes
+  sideby autostart off --yes
+Exit: 0 shown, done or nothing to change; 10 a change was shown and waits for --yes; 1 refused (not macOS, sideby
+in the npx cache or a temporary folder, a file that is not sideby's) or failed; 2 malformed command line.`,
+    config: `sideby config get [<key>] [--json]
+sideby config set <key> <value> [--yes] [--json]
+sideby config unset <key> [--yes] [--json]
+
+Read or change any setting in sideby's config file. <key> is a dot path such as handoff.threshold or panel.theme;
+\`sideby config get\` lists every key with its value, what it does and the values it takes. A value is read as
+JSON when it parses (90, true, ["cc002","codex001"]), otherwise as text (dark).
+
+set and unset show the change first; --yes saves it. The whole file must still be a valid config, and other keys
+and their order are kept. A plugin's own settings are not read or changed here (they may hold secrets), only
+plugins.<plugin>.enabled. accounts.<family>:<name>.args takes only the model and effort arguments, as
+\`sideby model\` does.
+
+Examples:
+  sideby config get --json
+  sideby config set panel.theme dark --yes
+  sideby config set handoff.threshold 90 --yes
+  sideby config unset panel.language --yes
+Exit: 0 shown, saved or nothing to change; 10 a change was shown and waits for --yes; 1 not a key, a value the key
+does not take, or the file changed meanwhile; 2 malformed command line.`,
     browser: `sideby browser [--enable|--disable] [--yes] [--json]
        sideby browser open <account> [--profile <folder|name>] [--json]
 
@@ -224,6 +279,12 @@ export function nodeTooOld(version = process.versions.node) {
     return maj < MIN_NODE[0] || (maj === MIN_NODE[0] && min < MIN_NODE[1]);
 }
 const COMMANDS = {
+    ask: { flags: ['json', 'print'], valued: ['task', 'account', 'terminal', 'run', 'state-dir', 'attach'] },
+    terminal: { flags: ['json', 'unset'], valued: ['set', 'custom'] },
+    key: { flags: ['json'], valued: ['var'] },
+    try: { flags: ['json', 'yes'] },
+    autostart: { flags: ['json', 'yes', 'refresh'] },
+    config: { flags: ['json', 'yes'] },
     list: { flags: ['json'] },
     pin: { flags: ['json'] },
     unpin: { flags: ['json'] },
@@ -254,10 +315,24 @@ const COMMANDS = {
     local: { flags: ['json', 'yes'] },
     'update-check': { flags: [] },
 };
+/** Every value of a repeatable option (`--attach a --attach=b`), in order. */
+function repeatedValues(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === `--${name}` && args[i + 1] !== undefined)
+            out.push(args[++i]);
+        else if (a.startsWith(`--${name}=`))
+            out.push(a.slice(name.length + 3));
+    }
+    return out;
+}
 /** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
 function noticeAllowed(cmd, parsed) {
     if (cmd === 'shell-init' || cmd === 'update' || cmd === 'update-check')
         return false;
+    if (cmd === 'ask' && (parsed.flags.has('print') || parsed.flags.has('run')))
+        return false;
     if (cmd === 'ui' && parsed.flags.has('serve-detached'))
         return false;
     if (cmd === 'handoff' && parsed.positionals[0] === 'ready')
@@ -349,7 +424,7 @@ export async function main(argv) {
         return runHandoffHook(rest, process.env, process.stdin, process.stdout);
     }
     if (nodeTooOld()) {
-        console.error(`sideby needs Node ${MIN_NODE.join('.')} or newer (you have ${process.versions.node}). Upgrade: https://nodejs.org`);
+        console.error(`sideby needs Node ${MIN_NODE.join('.')} or newer (you have ${process.versions.node}). Upgrade: https://nodejs.org, or with nvm: \`nvm install 22 && nvm alias default 22\`, then \`npm i -g sideby\` again (each Node version has its own global packages).`);
         return 1;
     }
     if (first === '-v' || first === '--version' || first === 'version') {
@@ -404,6 +479,9 @@ export async function main(argv) {
             console.log(COMMAND_HELP[cmd] ?? HELP);
             return 0;
         }
+        // parseArgs keeps the last value of an option; `ask --attach` may be given several times.
+        if (cmd === 'ask')
+            parsed.attach = repeatedValues(own, 'attach');
         const cmds = await import('./commands.js');
         if (wantsJson && noticeAllowed(cmd, parsed)) {
             notice = await jsonNoticeFor();
@@ -431,6 +509,14 @@ export async function main(argv) {
 }
 async function dispatch(cmd, parsed, io, cmds) {
     switch (cmd) {
+        case 'ask':
+            return cmds.cmdAsk(parsed, io);
+        case 'terminal':
+            return cmds.cmdTerminal(parsed, io);
+        case 'key':
+            return cmds.cmdKey(parsed, io);
+        case 'try':
+            return cmds.cmdTry(parsed, io);
         case 'pin':
         case 'unpin':
             return await cmds.cmdPin(parsed, io, cmd === 'pin');
@@ -482,6 +568,10 @@ async function dispatch(cmd, parsed, io, cmds) {
             return await cmds.cmdUpdateCheck(parsed, io);
         case 'local':
             return await cmds.cmdLocal(parsed, io);
+        case 'autostart':
+            return await cmds.cmdAutostart(parsed, io);
+        case 'config':
+            return await cmds.cmdConfig(parsed, io);
     }
     return 2;
 }

package/dist/src/core/ask.d.ts

@@ -0,0 +1,150 @@
+import { taskPrompt } from '../panel/page-logic.ts';
+import type { Runtime } from '../runtime.ts';
+import type { Account, Env } from '../types.ts';
+import { type Attachment } from './attachments.ts';
+import { type Paths } from './paths.ts';
+import { type ProbeDeps } from './probe.ts';
+import { type TerminalId } from './terminal.ts';
+export declare function pickTaskAccount(rt: Runtime, opts?: {
+    family?: string;
+    account?: string;
+}): Promise<{
+    account: Account;
+} | {
+    reason: 'no-accounts' | 'none-signed-in' | 'all-full';
+}>;
+export interface TaskFile {
+    kind: 'prompt' | 'login';
+    account: string;
+    prompt?: string;
+    cwd: string;
+    /** The Panel's paths when it wrote the task; `ask --run` starts the Host with the same HOME, config and state. */
+    home?: string;
+    configDir?: string;
+    stateDir?: string;
+    /** Files attached to the task (spec §3.28 "附件"), saved under `ai/attachments/<task-id>/`; never their content. */
+    attachments?: {
+        path: string;
+        kind: 'image' | 'video';
+    }[];
+}
+export declare function taskWorkDir(paths?: Paths): Promise<string>;
+export declare const newTaskId: () => string;
+export declare function writeTask(task: TaskFile, paths?: Paths, id?: string): Promise<string>;
+/**
+ * The state folder `ask --run --state-dir` names, accepted only when it and its `ask` folder are real directories the
+ * user owns that nobody else can write (the `ask` folder private, as writeTask makes it). Anything else is refused.
+ */
+export declare function taskStateDir(dir: string): Promise<string>;
+/**
+ * The Host arguments `ask --run` adds for a prompt task: `<imageArg>=<path>` per attached image for a Family that
+ * declares `imageArg` (spec §3.28 "附件"), then the prompt, always last. The `=` form keeps one value per option, so a
+ * Host option that takes several values cannot swallow the prompt. An image that is gone, or whose path holds a comma
+ * (a Host taking lists may split it), is left to the path in the prompt.
+ */
+export declare function taskHostArgs(rt: Runtime, task: TaskFile): Promise<string[]>;
+/** `env` with the HOME and XDG folders the task was written under, so the Runtime sees what the Panel saw. */
+export declare function taskEnv(task: TaskFile, env: Env): Env;
+export declare function readTask(id: string, paths?: Pick<Paths, 'stateDir'>): Promise<TaskFile>;
+export declare function terminals(rt: Runtime): Promise<{
+    installed: import("./terminal.ts").InstalledTerminal[];
+    preferred: string | null;
+    guess: {
+        id: TerminalId;
+        source: 'config' | 'env' | 'default';
+    };
+    terminals: {
+        id: TerminalId;
+        name: string;
+        bundleId: string | null;
+        app: string | null;
+        termPrograms: readonly string[];
+        marker?: string;
+        binary?: string;
+        installed: boolean;
+    }[];
+}>;
+export declare function setPreferredTerminal(rt: Runtime, id?: string): Promise<void>;
+/** Saves `terminal.custom` after checking it names a program and both placeholders; selects it too. */
+export declare function setCustomTerminal(rt: Runtime, template: string): Promise<void>;
+export interface AiTaskInput {
+    task?: string;
+    text?: string;
+    context?: Parameters<typeof taskPrompt>[0]['context'];
+    lang?: string;
+    account?: string;
+    family?: string;
+    terminal?: string;
+    /** With an explicit `account`: save it as `ask.account`, the next default. */
+    remember?: boolean;
+    /** Panel uploads (`/api/ask/attach` ids) to attach. */
+    uploads?: string[];
+    /** The user's own files to attach (`sideby ask --attach`). */
+    files?: string[];
+}
+/** The attachments a prompt shown before the task exists lists: uploads still staged, the user's files in place. */
+export declare function previewAttachments(rt: Runtime, input: AiTaskInput): Promise<Attachment[]>;
+export declare function promptForTask(rt: Runtime, input: AiTaskInput, attachments?: readonly Attachment[]): {
+    prompt: string;
+    removedSecrets: boolean;
+};
+/** Machine-readable reasons an AI Task did not open; `detail` says what to do. */
+export type AiTaskReason = 'no-accounts' | 'none-signed-in' | 'all-full' | 'not-installed' | 'automation-denied' | 'npx-cache' | 'unsafe-path' | 'failed' | 'unsupported-platform';
+export declare function startAiTask(rt: Runtime, input: AiTaskInput): Promise<{
+    schemaVersion: 1;
+    task: null;
+    account: null;
+    terminal: null;
+    opened: boolean;
+    command: null;
+    prompt: string;
+    reason: AiTaskReason;
+    detail: string;
+    removedSecrets: boolean;
+    attachments: Attachment[];
+} | {
+    schemaVersion: 1;
+    task: string;
+    account: string;
+    terminal: string;
+    opened: boolean;
+    command: string;
+    reason?: AiTaskReason | undefined;
+    detail?: string | undefined;
+    prompt?: undefined;
+    removedSecrets: boolean;
+    attachments: Attachment[];
+}>;
+export declare function openLoginInTerminal(rt: Runtime, ref: string): Promise<{
+    schemaVersion: 1;
+    task: string;
+    account: string;
+    terminal: string;
+    opened: boolean;
+    command: string;
+    reason?: AiTaskReason | undefined;
+    detail?: string | undefined;
+}>;
+/**
+ * What `try` will run for an Account, computed as `sideby run` would (Family defaults, config arguments) but without
+ * reading its Secret File or running `launch.before` hooks: nothing runs before the user agrees.
+ */
+export declare function tryPreview(rt: Runtime, ref: string): Promise<{
+    account: Account;
+    family: import("../types.ts").FamilyDef;
+    command: string[];
+}>;
+/**
+ * `sideby try` and the Panel (spec §3.28): runs the Family's probe once the way Launch starts the Host, in a temp
+ * folder under the task directory that is removed afterwards. The caller has already said it spends a few tokens. The
+ * launch is prepared once here, so `launch.before` hooks run once, and the command returned is what actually ran.
+ * `spawn` replaces the process start (tests); by default the Host runs with stdin ignored and is killed at the timeout.
+ */
+export declare function tryAccount(rt: Runtime, ref: string, spawn?: ProbeDeps['spawn']): Promise<{
+    ok: boolean;
+    exitCode: number | null;
+    output: string;
+    timedOut: boolean;
+    account: string;
+    command: string[];
+}>;