pendingyou 0.1.0 → 0.2.0

package/README.md

@@ -34,14 +34,40 @@ lines (the question, your answer, the next step) and exits. Claude Code wakes up
 When you're at the terminal, Claude Code asks you there and puts the same question in Pending You at once; the
 first answer wins. If you answer in the terminal, it withdraws the card and the hold ends by itself.
 
+## A computer with no browser
+
+On a server or over SSH, sign in with a code instead:
+
+```sh
+npx pendingyou login --device
+```
+
+It shows a short code. Open pendingyou.com/device on your phone, sign in, enter the code and press Allow. Only enter a
+code your own computer is showing you.
+
+## Always-on scripts
+
+`watch` runs a command each time an answer is ready, for a script on your assistant's own machine:
+
+```sh
+npx pendingyou watch -- ./on-answer.sh
+```
+
+When you sign in, pick which assistant it hears for ("Hear answers for: Only Muse"); by default it's your Claude Code
+assistants. The command runs without a shell, once per answer, message or fallback that comes due, oldest first. It
+gets the request as JSON on stdin, and `PENDINGYOU_REQUEST_ID`, `PENDINGYOU_EVENT` (`answer_ready`, `message_ready` or
+`fallback_due`), `PENDINGYOU_VERSION` and `PENDINGYOU_ORIGIN` in its environment. A failing command is tried twice
+more, then skipped. `--once` stops after the first.
+
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init` | Set up Claude Code on this computer (`--no-login`, `--no-browser`) |
+| `init` | Set up Claude Code on this computer (`--no-login`, `--no-browser`, `--device`) |
 | `hold <requestId>` | Wait for the answer, print it, exit (`--timeout 4h`) |
 | `status` | What's set up; exits 0 when Claude Code hears answers right away |
-| `login` / `logout` | Sign this computer in or out (`--force`, `--all`) |
+| `login` / `logout` | Sign this computer in or out (`--device`, `--force`, `--all`) |
+| `watch -- <command>` | Run a command each time an answer is ready (`--once`) |
 | `pickup` / `handoff` | The session-start and next-message hooks |
 | `uninstall` | Remove what `init` added, and sign out |
 
@@ -49,7 +75,7 @@ Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDI
 
 ## What it can see, and where it keeps things
 
-The sign-in only hears answers to your own Claude Code assistants' questions. It isn't an assistant: it can't ask,
+The sign-in only hears answers to your own Claude Code assistants' questions, or to the one assistant you picked. It isn't an assistant: it can't ask,
 answer or change anything, and it doesn't show up as one. It's stored in `~/.config/pendingyou/credentials.json`
 (readable only by you), refreshes itself, and ends after 30 days or on `logout`. `state.json` beside it remembers
 which answers were already handed over (ids only). Nothing is sent anywhere but Pending You.

package/dist/args.js

@@ -46,19 +46,21 @@ const COMMANDS = new Set([
     'handoff',
     'init',
     'uninstall',
+    'watch',
 ]);
 /** Flags each command takes; `true` when the flag takes a value. */
 const FLAGS = {
     help: {},
     version: {},
-    login: { origin: true, 'no-browser': false, force: false },
+    login: { origin: true, 'no-browser': false, force: false, device: false },
     logout: { origin: true, all: false },
     status: { origin: true },
     hold: { origin: true, timeout: true },
     pickup: { origin: true },
     handoff: { origin: true },
-    init: { origin: true, 'no-login': false, 'no-browser': false },
+    init: { origin: true, 'no-login': false, 'no-browser': false, device: false },
     uninstall: { origin: true },
+    watch: { origin: true, once: false },
 };
 export function parseArgs(argv, env = {}) {
     const [first, ...rest] = argv;
@@ -71,8 +73,14 @@ export function parseArgs(argv, env = {}) {
     const allowed = FLAGS[first] ?? {};
     const flags = new Map();
     const positional = [];
+    // `watch -- <command> [args…]`: everything after `--` is the command, taken as it is.
+    let command;
     for (let index = 0; index < rest.length; index++) {
         const arg = rest[index];
+        if (arg === '--' && first === 'watch') {
+            command = rest.slice(index + 1);
+            break;
+        }
         if (arg === '-h' || arg === '--help')
             return { name: 'help' };
         if (!arg.startsWith('--')) {
@@ -112,7 +120,13 @@ export function parseArgs(argv, env = {}) {
             return { name: 'version' };
         case 'login':
             none();
-            return { name: 'login', origin, browser: !flags.has('no-browser'), force: flags.has('force') };
+            return {
+                name: 'login',
+                origin,
+                browser: !flags.has('no-browser'),
+                force: flags.has('force'),
+                device: flags.has('device'),
+            };
         case 'logout':
             none();
             return { name: 'logout', origin, all: flags.has('all') };
@@ -135,7 +149,13 @@ export function parseArgs(argv, env = {}) {
                 origin,
                 login: !flags.has('no-login'),
                 browser: !flags.has('no-browser'),
+                device: flags.has('device'),
             };
+        case 'watch':
+            none();
+            if (!command?.length || !command[0])
+                throw new UsageError('watch needs a command after --, like: pendingyou watch -- ./on-answer.sh');
+            return { name: 'watch', origin, command, once: flags.has('once') };
         case 'hold': {
             if (positional.length !== 1)
                 throw new UsageError('hold needs one request id, like: pendingyou hold req_0123…');
@@ -158,11 +178,14 @@ export const USAGE = `pendingyou: Pending You for Claude Code
   npx pendingyou hold <req_…>  Wait in the background until the answer to a request is ready,
                                print it, and exit (which wakes Claude Code)
   npx pendingyou status        What's set up, and whether Claude Code hears answers right away
-  npx pendingyou login | logout
+  npx pendingyou login [--device] | logout
+                               --device: on a computer with no browser, approve a short code on your phone
+  npx pendingyou watch -- <command> [args…]
+                               Run a command each time an answer is ready (always-on scripts)
   npx pendingyou uninstall     Remove exactly what init added
   npx pendingyou pickup        Answers waiting for this folder (the session-start hook)
   npx pendingyou handoff       The same, only while a hold is outstanding (the next-message hook)
 
-Options: --origin <url> (default ${DEFAULT_ORIGIN}), --timeout 4h (hold), --no-browser (login, init),
---no-login (init), --all (logout), --force (login).
+Options: --origin <url> (default ${DEFAULT_ORIGIN}), --timeout 4h (hold), --no-browser and --device (login,
+init), --no-login (init), --all (logout), --force (login), --once (watch).
 `;

package/dist/index.js

@@ -3,5 +3,5 @@ export { getJson, SignInNeeded, Unavailable } from "./api.js";
 export { DEFAULT_ORIGIN, parseArgs } from "./args.js";
 export { readCredential, updateCredential } from "./credentials.js";
 export { main } from "./main.js";
-export { CLIENT_NAME, discover, register, revoke, SCOPE, signIn } from "./oauth.js";
+export { CLIENT_NAME, discover, register, revoke, SCOPE, signIn, signInWithDevice, } from "./oauth.js";
 export { VERSION } from "./version.js";

package/dist/io.js

@@ -28,6 +28,38 @@ export function runProgram(command, args, timeoutMs = 60_000) {
         child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
     });
 }
+export function execProgram(command, args, options) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, [...args], {
+                stdio: ['pipe', 'inherit', 'inherit'],
+                env: { ...process.env, ...options.env },
+                windowsHide: true,
+            });
+        }
+        catch {
+            resolve(127);
+            return;
+        }
+        let timedOut = false;
+        const stop = () => child.kill('SIGTERM');
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, options.timeoutMs);
+        options.signal?.addEventListener('abort', stop, { once: true });
+        const done = (code) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', stop);
+            resolve(code);
+        };
+        child.on('error', (error) => done(error.code === 'ENOENT' ? 127 : 1));
+        child.on('close', (code) => done(timedOut ? 124 : (code ?? 1)));
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(options.stdin);
+    });
+}
 export function sleep(ms, signal) {
     return new Promise((resolve) => {
         if (signal?.aborted || ms <= 0) {
@@ -93,6 +125,7 @@ export function realIo() {
         err: (text) => process.stderr.write(text),
         fetch: (input, init) => fetch(input, init),
         run: runProgram,
+        exec: execProgram,
         openBrowser,
         readStdin,
         now: () => Date.now(),

package/dist/main.js

@@ -6,16 +6,21 @@ import { claudeState, installClaude, uninstallClaude } from "./claude.js";
 import { readCredential, signedInOrigins, updateCredential } from "./credentials.js";
 import { PlainError } from "./errors.js";
 import { hold } from "./hold.js";
-import { OAuthError, revoke, signIn } from "./oauth.js";
+import { OAuthError, revoke, signIn, signInWithDevice } from "./oauth.js";
 import { pickup } from "./pickup.js";
 import { VERSION } from "./version.js";
+import { watch } from "./watch.js";
 /** Whether this computer's sign-in works, and how many Claude Code connections it hears for. */
 async function checkSignIn(io, origin) {
     try {
         const { status, body } = await getJson(io, origin, '/mcp/cli/answers?limit=0', 15_000, io.signal);
         if (status !== 200)
             return { state: 'unreachable' };
-        return { state: 'ok', connections: body.connections ?? 0 };
+        return {
+            state: 'ok',
+            connections: body.connections ?? 0,
+            ...(body.for ? { for: body.for } : {}),
+        };
     }
     catch (error) {
         if (error instanceof SignInNeeded)
@@ -32,10 +37,9 @@ async function login(io, options) {
         }
     }
     const previous = await readCredential(io, options.origin);
-    const { clientId, tokens } = await signIn(io, {
-        origin: options.origin,
-        browser: options.browser,
-    });
+    const { clientId, tokens } = options.device
+        ? await signInWithDevice(io, { origin: options.origin })
+        : await signIn(io, { origin: options.origin, browser: options.browser });
     await updateCredential(io, options.origin, () => ({
         clientId,
         ...tokens,
@@ -70,7 +74,9 @@ async function status(io, origin) {
     const lines = [`Pending You for Claude Code · ${origin}`];
     const mark = (ok) => (ok ? 'ok     ' : 'missing');
     lines.push(`  ${mark(signIn.state === 'ok')} Sign-in: ${signIn.state === 'ok'
-        ? `hears for ${signIn.connections} Claude Code connection${signIn.connections === 1 ? '' : 's'}`
+        ? signIn.for
+            ? `hears for ${signIn.for.name} only (for pendingyou watch)`
+            : `hears for ${signIn.connections} Claude Code connection${signIn.connections === 1 ? '' : 's'}`
         : signIn.state === 'ended'
             ? 'ended; run npx pendingyou login'
             : signIn.state === 'none'
@@ -90,7 +96,12 @@ async function init(io, options) {
         io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`);
     if (options.login) {
         io.out('Signing this computer in, so answers can wake Claude Code:\n');
-        await login(io, { origin: options.origin, browser: options.browser, force: false });
+        await login(io, {
+            origin: options.origin,
+            browser: options.browser,
+            device: options.device,
+            force: false,
+        });
     }
     else
         io.out('Skipped signing in. Run npx pendingyou login when you’re ready.\n');
@@ -128,6 +139,8 @@ async function run(io, command) {
             return init(io, command);
         case 'uninstall':
             return uninstall(io, command.origin);
+        case 'watch':
+            return watch(io, command);
     }
 }
 export async function main(argv, io) {

package/dist/oauth.js

@@ -233,3 +233,72 @@ export async function revoke(io, origin, clientId, refreshToken) {
         return false;
     }
 }
+/**
+ * Device sign-in (RFC 8628) for a computer with no browser: shows a short code and where to enter it, then polls until
+ * the person presses Allow on their phone (or Cancel, or the code runs out).
+ */
+export async function signInWithDevice(io, options) {
+    const metadata = await discover(io, options.origin);
+    const clientId = await register(io, metadata);
+    const started = await io.fetch(`${options.origin}/oauth/device`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({ client_id: clientId, scope: SCOPE }).toString(),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const start = (await started.json().catch(() => ({})));
+    if (!started.ok || typeof start.device_code !== 'string' || typeof start.user_code !== 'string')
+        throw new OAuthError(start.error ?? `http_${started.status}`, start.error === 'slow_down'
+            ? 'Too many sign-ins from here. Wait 10 minutes, then try again.'
+            : `Pending You didn’t start a device sign-in (${started.status}).`);
+    const page = start.verification_uri ?? `${options.origin}/device`;
+    if (new URL(page).origin !== options.origin)
+        throw new OAuthError('discovery', 'Pending You sent the sign-in page somewhere else.');
+    io.err(`On your phone or any browser, open ${page} and enter this code:\n\n    ${start.user_code}\n\n` +
+        `Or go straight to ${start.verification_uri_complete ?? `${page}?code=${start.user_code}`}\nWaiting for you to press Allow…\n`);
+    let interval = Math.max(1, start.interval ?? 5) * 1000;
+    const deadline = io.now() + Math.max(60, start.expires_in ?? 600) * 1000;
+    for (;;) {
+        await io.sleep(interval, io.signal);
+        if (io.signal.aborted)
+            throw new OAuthError('interrupted', 'Signing in was stopped.');
+        if (io.now() > deadline)
+            throw new OAuthError('expired_token', 'The code ran out. Run the command again for a new one.');
+        const response = await io.fetch(`${options.origin}/oauth/device/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams({
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: start.device_code,
+                client_id: clientId,
+            }).toString(),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (response.ok &&
+            typeof body.access_token === 'string' &&
+            typeof body.refresh_token === 'string') {
+            const seconds = typeof body.expires_in === 'number' ? body.expires_in : 900;
+            return {
+                clientId,
+                tokens: {
+                    accessToken: body.access_token,
+                    refreshToken: body.refresh_token,
+                    expiresAt: io.now() + seconds * 1000,
+                },
+            };
+        }
+        const error = typeof body.error === 'string' ? body.error : `http_${response.status}`;
+        if (error === 'authorization_pending')
+            continue;
+        if (error === 'slow_down') {
+            interval += 5000;
+            continue;
+        }
+        if (error === 'access_denied')
+            throw new OAuthError(error, 'You pressed Cancel, so this computer isn’t signed in.');
+        if (error === 'expired_token')
+            throw new OAuthError(error, 'The code ran out. Run the command again for a new one.');
+        throw new OAuthError(error, `Pending You refused the sign-in (${error}).`);
+    }
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 // The command line's version, as published (package.json). A test keeps them the same.
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';

package/dist/watch.js

@@ -0,0 +1,132 @@
+// `pendingyou watch -- <command> [args…]`: for an always-on script on an assistant's own machine (a Muse job, a cron
+// box, a home server). It waits on Pending You for any of the sign-in's requests to become the assistant's move, and
+// runs the command once for each: the answer after its 5-second hold, a message from the person, or a fallback that
+// came due. Point the sign-in at one assistant on the consent page ("Hear answers for: Only Muse"); without that it
+// watches the person's Claude Code assistants.
+//
+// The command runs without a shell, one at a time, with its output passed through. It gets the request on stdin as
+// JSON (the same fields as /mcp/cli/answers: id, title, status, the answer in words, new messages, fallback) and, in
+// the environment, PENDINGYOU_REQUEST_ID, PENDINGYOU_EVENT (answer_ready, message_ready or fallback_due),
+// PENDINGYOU_VERSION (for ack_answer's expectedVersion) and PENDINGYOU_ORIGIN. Nothing about the answer goes in the
+// environment or the arguments, where other programs could see it. The script then acts through its own assistant
+// (get_request, ack_answer): watch only reads.
+//
+// A command that fails (a non-zero exit, or 5 minutes without finishing) is tried twice more, 5 and 15 seconds
+// apart, then left: watch says so and moves on, so one bad answer can't wedge it. A command that can't be started at
+// all stops watch (exit 127) without handing anything over. What was handed over is remembered
+// (state.json), so a restart doesn't run anything twice. --once exits after the first, with the command's exit code.
+import { getJson, SignInNeeded, Unavailable } from "./api.js";
+import { readCredential } from "./credentials.js";
+import { markHanded, momentOf, wasHanded } from "./state.js";
+const LONG_POLL_SECONDS = 25;
+const COMMAND_MS = 5 * 60 * 1000;
+const RETRY_MS = [5000, 15_000];
+const PATIENT_AFTER_MS = 30 * 60 * 1000;
+const PATIENT_PAUSE_MS = 30_000;
+const BACKOFF_MS = [2000, 5000, 10_000, 20_000, 30_000, 60_000];
+export function eventOf(heard) {
+    if (heard.status === 'answered')
+        return 'answer_ready';
+    if (heard.status === 'expired')
+        return 'fallback_due';
+    return 'message_ready';
+}
+export async function watch(io, options) {
+    const { origin } = options;
+    const [program, ...args] = options.command;
+    const say = (text) => io.err(`pendingyou watch: ${text}\n`);
+    if (!(await readCredential(io, origin))) {
+        say('this computer isn’t signed in. Run `npx pendingyou login` (or `login --device` without a browser).');
+        return 1;
+    }
+    say(`watching ${origin}. Ctrl-C stops.`);
+    let since;
+    let quietSince = io.now();
+    let failures = 0;
+    for (;;) {
+        if (io.signal.aborted) {
+            say('stopped.');
+            return 0;
+        }
+        const query = new URLSearchParams({ limit: '20', wait: String(LONG_POLL_SECONDS) });
+        if (since)
+            query.set('since', since);
+        let result;
+        try {
+            result = await getJson(io, origin, `/mcp/cli/answers?${query}`, (LONG_POLL_SECONDS + 20) * 1000, io.signal);
+        }
+        catch (error) {
+            if (io.signal.aborted)
+                continue;
+            if (error instanceof SignInNeeded) {
+                say(error.ended
+                    ? 'the sign-in has ended. Run `npx pendingyou login` again.'
+                    : 'this computer isn’t signed in. Run `npx pendingyou login`.');
+                return 1;
+            }
+            const pause = error instanceof Unavailable && error.retryAfter
+                ? error.retryAfter * 1000
+                : BACKOFF_MS[Math.min(failures, BACKOFF_MS.length - 1)];
+            failures++;
+            await io.sleep(pause, io.signal);
+            continue;
+        }
+        failures = 0;
+        const heard = Array.isArray(result.body.requests) ? result.body.requests : [];
+        if (result.status !== 200) {
+            await io.sleep(BACKOFF_MS[1], io.signal);
+            continue;
+        }
+        for (const request of heard)
+            if (!since || request.changedAt > since)
+                since = request.changedAt;
+        // Oldest first, and only what this computer hasn't handed over yet.
+        const fresh = [];
+        for (const request of [...heard].sort((a, b) => a.changedAt.localeCompare(b.changedAt)))
+            if (!(await wasHanded(io, origin, request.requestId, momentOf(request))))
+                fresh.push(request);
+        for (const request of fresh) {
+            if (io.signal.aborted)
+                break;
+            const code = await runFor(io, program, args, origin, request, say);
+            // A command that can't even start is a mistake in the command line: stop, and hand nothing over.
+            if (code === 127)
+                return 127;
+            await markHanded(io, origin, [
+                { requestId: request.requestId, moment: momentOf(request), closed: true },
+            ]);
+            if (options.once)
+                return code;
+        }
+        if (fresh.length > 0)
+            quietSince = io.now();
+        else if (io.now() - quietSince > PATIENT_AFTER_MS)
+            await io.sleep(PATIENT_PAUSE_MS, io.signal);
+    }
+}
+/** Runs the command for one request, trying twice more if it fails. Returns its last exit code. */
+async function runFor(io, program, args, origin, request, say) {
+    const env = {
+        PENDINGYOU_REQUEST_ID: request.requestId,
+        PENDINGYOU_EVENT: eventOf(request),
+        PENDINGYOU_VERSION: String(request.version),
+        PENDINGYOU_ORIGIN: origin,
+    };
+    const stdin = `${JSON.stringify(request)}\n`;
+    let code = 0;
+    for (let attempt = 0; attempt <= RETRY_MS.length; attempt++) {
+        if (attempt > 0)
+            await io.sleep(RETRY_MS[attempt - 1], io.signal);
+        if (io.signal.aborted)
+            return code;
+        code = await io.exec(program, args, { env, stdin, timeoutMs: COMMAND_MS, signal: io.signal });
+        if (code === 0)
+            return 0;
+        if (code === 127) {
+            say(`couldn’t start ${program}. Check the command after --. Stopping.`);
+            return code;
+        }
+    }
+    say(`the command failed for ${request.requestId} (exit ${code}) three times; moving on.`);
+    return code;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pendingyou",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pending You for Claude Code: hear your answers from Pending You in the background, and set Claude Code up in one command.",
   "license": "Apache-2.0",
   "homepage": "https://www.pendingyou.com",