@mjasnikovs/pi-task 0.2.3 → 0.4.0

package/README.md

@@ -64,6 +64,7 @@ pi install npm:@mjasnikovs/pi-task
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume` | Resume the active `/task-auto` run at the next unfinished task. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
+| `/remote` | Show the QR code & URLs for the always-on web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
 
@@ -103,6 +104,18 @@ A real feature is usually several tasks, not one. `/task-auto` is a thin planner
 - **Sequential, blocking.** Each title runs through `/task` to a spec, the spec is implemented, and the loop waits for that to finish before starting the next title. No overlap.
 - **Crash- and cancel-safe.** Progress is the markdown checkboxes in the AUTO file. `/task-auto-resume` (no id) automatically picks up the active run at the first unchecked title. If a title's `/task` run fails, the loop stops and leaves the run resumable.
 
+## Remote — drive a task from your phone
+
+The remote server is **always on** — it starts automatically with each session, with nothing taking up screen space. Run `/remote` any time to pop a QR code and the connection URLs: a **Tailscale** line and a **LAN** line when both are available (the QR encodes the Tailscale-preferred one). Open the URL on any device that can reach the host and you get a live view of the session: streaming output, tool calls, and the `/task` status block (phase, elapsed, context). It's bidirectional — the browser can:
+
+- **Answer grill / `/task-auto` clarify questions.** Each question appears as a card with the recommended default pre-filled (Accept), a free-text box (Submit), Skip, or Cancel task.
+- **Start and control tasks.** Type `/task …`, `/task-auto …`, `/task-cancel`, `/task-resume`, etc. — they run on the host.
+- **Send plain messages** to the agent.
+
+Prompts use a **first-answer-wins race**: the same question shows in the local TUI *and* every connected browser, and whoever answers first wins — the other surfaces dismiss. With nobody connected, `/task` behaves exactly as before; the remote path is purely additive.
+
+`/remote stop` shuts the server down for the rest of the session (it comes back on the next session start). There is **no authentication** — it's a personal LAN/Tailscale tool. Don't expose the port to untrusted networks.
+
 ## Bundled tools
 
 `pi-task` also registers four MCP-style worker tools (formerly `@mjasnikovs/pi-worker`). All are parallel-execution-capable, so the parent session can issue several calls in one turn.

package/dist/index.js

@@ -1,8 +1,10 @@
 import { registerTask } from './task/orchestrator.js';
 import { registerTaskAuto } from './task/auto-orchestrator.js';
 import { registerWorkers } from './workers/index.js';
+import { registerRemote } from './remote/register.js';
 export default function (pi) {
     registerTask(pi);
     registerTaskAuto(pi);
     registerWorkers(pi);
+    registerRemote(pi);
 }

package/dist/remote/bridge.d.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { PromptMessage, ServerMessage } from './protocol.js';
+export interface BridgeState {
+    /** promptId → resolver that settles the remote side of an ask() race. */
+    pending: Map<string, (value: string | undefined) => void>;
+    /** The prompt currently awaiting an answer (replayed to late joiners), or null. */
+    activePrompt: PromptMessage | null;
+    /** Last lines pushed per widget key (replayed to late joiners). */
+    activeWidgets: Map<string, string[]>;
+    nextId: number;
+    /** Command name → handler, populated as pi-task registers its commands. */
+    commands: Map<string, (args: string, ctx: ExtensionCommandContext) => unknown>;
+    /** Most recent live command context, for remote-initiated dispatch. */
+    currentCtx: ExtensionCommandContext | null;
+    /** Broadcast sink — swapped in tests. */
+    broadcast: (msg: ServerMessage) => void;
+    /** @internal Test-only capture of broadcast messages; empty in production. */
+    sent: ServerMessage[];
+}
+export declare function getBridge(): BridgeState;
+/** Resolve the remote side of a pending prompt. First call wins; later calls
+ *  (duplicate frames, a second browser, local-after-remote) are ignored. */
+export declare function answerPrompt(id: string, value: string | undefined): void;
+export interface AskSpec {
+    /** Themed, possibly multi-line title for the local TUI input. */
+    localTitle: string;
+    /** Plain question text for the browser card. */
+    question: string;
+    /** Plain recommended default (prefilled in both surfaces), if any. */
+    recommended?: string;
+    /** Whether the browser card shows a Skip button (answers with empty string). */
+    allowSkip: boolean;
+}
+/** Wraps a live command ctx and fans interactions out to local TUI + browsers. */
+export declare class SessionUI {
+    private readonly ctx;
+    private readonly bridge;
+    constructor(ctx: ExtensionCommandContext, bridge?: BridgeState);
+    get theme(): ExtensionCommandContext['ui']['theme'];
+    get hasUI(): boolean;
+    /** Race the local input against a remote answer; first to settle wins. */
+    ask(spec: AskSpec): Promise<string | undefined>;
+}
+/** Mirror a status widget to browsers and remember it for late joiners.
+ *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
+export declare function publishWidget(key: string, lines: string[] | undefined): void;
+export declare function publishNotify(message: string, level: 'info' | 'warning' | 'error'): void;
+export declare function publishViewer(title: string, text: string): void;
+interface BridgeCommandDef {
+    description: string;
+    handler: (args: string, ctx: ExtensionCommandContext) => unknown;
+    [k: string]: unknown;
+}
+/** Register a command with pi AND record it in the bridge so remote slash lines
+ *  can invoke it. Use in place of pi.registerCommand for task commands. */
+export declare function registerBridgeCommand(pi: ExtensionAPI, name: string, def: BridgeCommandDef): void;
+/** Start a new session in response to a remote `/new`. Reads the freshest
+ *  command-capable ctx (currentCtx) at call time and mirrors dispatchRemoteLine's
+ *  guards: a missing, non-command, or stale ctx toasts instead of crashing.
+ *
+ *  The crash this prevents: a captured ctx goes stale after a *local* /new (a
+ *  replacement we don't initiate, so we never get a withSession to rebind), and
+ *  ctx.newSession() then throws *synchronously* from assertActive — a sync throw
+ *  that a bare `.catch()` on the result would miss. `rebind` runs as withSession
+ *  with the fresh post-replacement ctx. */
+/** The richer context the runtime passes to a `newSession` withSession callback
+ *  (it carries sendUserMessage, unlike a plain command ctx). Derived from the
+ *  newSession signature since the package root doesn't re-export the type. */
+type NewSessionOptions = NonNullable<Parameters<ExtensionCommandContext['newSession']>[0]>;
+type ReplacedSessionContext = Parameters<NonNullable<NewSessionOptions['withSession']>>[0];
+export declare function dispatchRemoteNewSession(rebind: (ctx: ReplacedSessionContext) => void): void;
+/** Handle one line typed in a browser. Returns true if it was consumed as a
+ *  slash command (registered or unknown); false if it's a plain chat line that
+ *  the caller should forward via onPlain. */
+export declare function dispatchRemoteLine(text: string, opts: {
+    onPlain: (text: string) => void;
+}): boolean;
+export {};

package/dist/remote/bridge.js

@@ -0,0 +1,184 @@
+import { broadcast as wsBroadcast } from './broadcast.js';
+const g = globalThis;
+export function getBridge() {
+    if (!g.__piBridge) {
+        g.__piBridge = {
+            pending: new Map(),
+            activePrompt: null,
+            activeWidgets: new Map(),
+            nextId: 0,
+            commands: new Map(),
+            currentCtx: null,
+            broadcast: (msg) => wsBroadcast(msg),
+            sent: []
+        };
+    }
+    return g.__piBridge;
+}
+/** Resolve the remote side of a pending prompt. First call wins; later calls
+ *  (duplicate frames, a second browser, local-after-remote) are ignored. */
+export function answerPrompt(id, value) {
+    const b = getBridge();
+    const settle = b.pending.get(id);
+    if (!settle)
+        return;
+    b.pending.delete(id);
+    settle(value);
+}
+/** Wraps a live command ctx and fans interactions out to local TUI + browsers. */
+export class SessionUI {
+    ctx;
+    bridge;
+    constructor(ctx, bridge = getBridge()) {
+        this.ctx = ctx;
+        this.bridge = bridge;
+    }
+    get theme() {
+        return this.ctx.ui.theme;
+    }
+    get hasUI() {
+        return this.ctx.hasUI;
+    }
+    /** Race the local input against a remote answer; first to settle wins. */
+    async ask(spec) {
+        const b = this.bridge;
+        const id = String(b.nextId++);
+        const ac = new AbortController();
+        const remote = new Promise(resolve => {
+            b.pending.set(id, resolve);
+        });
+        const prompt = {
+            type: 'prompt',
+            id,
+            question: spec.question,
+            recommended: spec.recommended,
+            allowSkip: spec.allowSkip
+        };
+        b.activePrompt = prompt;
+        b.broadcast(prompt);
+        // Local: resolves to a value/undefined, or undefined on abort. Swallow
+        // the rejection some implementations throw on abort so it never leaks.
+        const local = this.ctx.hasUI ?
+            this.ctx.ui
+                .input(spec.localTitle, spec.recommended, { signal: ac.signal })
+                .catch(() => undefined)
+            : new Promise(() => { });
+        try {
+            const winner = await Promise.race([
+                local.then(v => ({ from: 'local', v })),
+                remote.then(v => ({ from: 'remote', v }))
+            ]);
+            if (winner.from === 'remote')
+                ac.abort();
+            return winner.v;
+        }
+        finally {
+            b.pending.delete(id);
+            b.activePrompt = null;
+            b.broadcast({ type: 'prompt_resolved', id });
+        }
+    }
+}
+/** Mirror a status widget to browsers and remember it for late joiners.
+ *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
+export function publishWidget(key, lines) {
+    const b = getBridge();
+    if (lines === undefined) {
+        b.activeWidgets.delete(key);
+        b.broadcast({ type: 'widget', key, lines: null });
+        return;
+    }
+    b.activeWidgets.set(key, lines);
+    b.broadcast({ type: 'widget', key, lines });
+}
+export function publishNotify(message, level) {
+    getBridge().broadcast({ type: 'notify', message, level });
+}
+export function publishViewer(title, text) {
+    getBridge().broadcast({ type: 'viewer', title, text });
+}
+/** Register a command with pi AND record it in the bridge so remote slash lines
+ *  can invoke it. Use in place of pi.registerCommand for task commands. */
+export function registerBridgeCommand(pi, name, def) {
+    const b = getBridge();
+    const wrapped = {
+        ...def,
+        handler: (args, ctx) => {
+            b.currentCtx = ctx; // keep latest live ctx for remote dispatch
+            return def.handler(args, ctx);
+        }
+    };
+    b.commands.set(name, wrapped.handler);
+    pi.registerCommand(name, wrapped);
+}
+export function dispatchRemoteNewSession(rebind) {
+    const b = getBridge();
+    const ctx = b.currentCtx;
+    if (!ctx) {
+        publishNotify('Start a session before running /new remotely.', 'warning');
+        return;
+    }
+    // A bare event-scoped ctx lacks newSession; a stale command ctx still has it
+    // but throws on call — the try/catch below covers that case.
+    if (typeof ctx.waitForIdle !== 'function') {
+        publishNotify('Session changed locally — run any task command in the terminal once to re-enable remote /new.', 'warning');
+        return;
+    }
+    const toastErr = (err) => publishNotify(`/new failed: ${err.message}`, 'error');
+    try {
+        const result = ctx.newSession({
+            // eslint-disable-next-line @typescript-eslint/require-await
+            withSession: async (newCtx) => {
+                b.currentCtx = newCtx;
+                rebind(newCtx);
+            }
+        });
+        if (result instanceof Promise)
+            result.catch(toastErr);
+    }
+    catch (err) {
+        toastErr(err);
+    }
+}
+/** Handle one line typed in a browser. Returns true if it was consumed as a
+ *  slash command (registered or unknown); false if it's a plain chat line that
+ *  the caller should forward via onPlain. */
+export function dispatchRemoteLine(text, opts) {
+    const b = getBridge();
+    if (!text.startsWith('/')) {
+        opts.onPlain(text);
+        return false;
+    }
+    const space = text.indexOf(' ');
+    const name = (space === -1 ? text.slice(1) : text.slice(1, space)).trim();
+    const args = space === -1 ? '' : text.slice(space + 1).trim();
+    const handler = b.commands.get(name);
+    if (!handler) {
+        publishNotify(`Unknown command: /${name}`, 'warning');
+        return true;
+    }
+    if (!b.currentCtx) {
+        publishNotify('Start a session before running commands remotely.', 'warning');
+        return true;
+    }
+    // Command handlers need a command-capable ctx (waitForIdle/newSession). A bare
+    // event-scoped ExtensionContext lacks those; if currentCtx is one (e.g. nothing
+    // command-capable has been captured yet), toast instead of throwing a TypeError.
+    if (typeof b.currentCtx.waitForIdle !== 'function') {
+        publishNotify('Session changed locally — run any task command in the terminal once to re-enable remote commands.', 'warning');
+        return true;
+    }
+    // Invoke synchronously so the call happens immediately, but surface both
+    // sync throws and async rejections from the (often async) command handler
+    // as a toast instead of crashing or becoming an unhandled rejection.
+    const toastErr = (err) => publishNotify(`/${name} failed: ${err.message}`, 'error');
+    try {
+        const result = handler(args, b.currentCtx);
+        if (result instanceof Promise)
+            result.catch(toastErr);
+    }
+    catch (err) {
+        toastErr(err);
+    }
+    return true;
+}

package/dist/remote/broadcast.d.ts

@@ -0,0 +1,6 @@
+import type { WebSocket } from 'ws';
+export declare function addClient(ws: WebSocket): void;
+export declare function removeClient(ws: WebSocket): void;
+export declare function clientCount(): number;
+export declare function broadcast(msg: unknown): void;
+export declare function sendTo(ws: WebSocket, msg: unknown): void;

package/dist/remote/broadcast.js

@@ -0,0 +1,27 @@
+// globalThis persists across jiti module re-evaluations on session switches
+const g = globalThis;
+if (!g.__piRemoteClients)
+    g.__piRemoteClients = new Set();
+const clients = g.__piRemoteClients;
+export function addClient(ws) {
+    clients.add(ws);
+}
+export function removeClient(ws) {
+    clients.delete(ws);
+}
+export function clientCount() {
+    return clients.size;
+}
+export function broadcast(msg) {
+    const json = JSON.stringify(msg);
+    for (const ws of clients) {
+        if (ws.readyState === ws.OPEN) {
+            ws.send(json);
+        }
+    }
+}
+export function sendTo(ws, msg) {
+    if (ws.readyState === ws.OPEN) {
+        ws.send(JSON.stringify(msg));
+    }
+}

package/dist/remote/events.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { HistoryBuffer } from './history.js';
+export declare function setupEvents(pi: ExtensionAPI, history: HistoryBuffer, broadcastFn: (msg: unknown) => void): void;

package/dist/remote/events.js

@@ -0,0 +1,81 @@
+import { setAgentIdle } from './state.js';
+export function setupEvents(pi, history, broadcastFn) {
+    let currentText = '';
+    const currentTools = [];
+    const pendingArgs = new Map();
+    pi.on('agent_start', (_event, _ctx) => {
+        currentText = '';
+        currentTools.length = 0;
+        pendingArgs.clear();
+        setAgentIdle(false);
+        broadcastFn({ type: 'agent_start' });
+    });
+    pi.on('message_update', (event, _ctx) => {
+        const ae = event.assistantMessageEvent;
+        if (ae.type === 'text_delta' && 'delta' in ae && typeof ae.delta === 'string') {
+            currentText += ae.delta;
+            broadcastFn({ type: 'text_delta', delta: ae.delta });
+        }
+        else if (ae.type === 'error') {
+            const errorMessage = 'error' in ae && ae.error && typeof ae.error.errorMessage === 'string' ?
+                ae.error.errorMessage
+                : '';
+            // Skip silent user aborts (no message); only surface genuine failures.
+            if (errorMessage || ae.reason === 'error') {
+                const message = errorMessage || 'Request failed';
+                history.addError(message);
+                broadcastFn({ type: 'agent_error', message });
+            }
+        }
+    });
+    pi.on('message_end', (_event, _ctx) => {
+        broadcastFn({ type: 'text_end' });
+    });
+    pi.on('tool_execution_start', (event, _ctx) => {
+        pendingArgs.set(event.toolCallId, event.args);
+        broadcastFn({
+            type: 'tool_start',
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            args: event.args
+        });
+    });
+    pi.on('tool_execution_update', (event, _ctx) => {
+        broadcastFn({
+            type: 'tool_update',
+            toolCallId: event.toolCallId,
+            partialResult: event.partialResult
+        });
+    });
+    pi.on('tool_execution_end', (event, _ctx) => {
+        const args = pendingArgs.get(event.toolCallId);
+        pendingArgs.delete(event.toolCallId);
+        currentTools.push({
+            toolName: event.toolName,
+            args,
+            result: event.result,
+            isError: event.isError
+        });
+        broadcastFn({
+            type: 'tool_end',
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            result: event.result,
+            isError: event.isError
+        });
+    });
+    pi.on('agent_end', (_event, ctx) => {
+        const contextUsage = ctx.getContextUsage();
+        setAgentIdle(true);
+        history.addAssistantTurn(currentText, [...currentTools]);
+        broadcastFn({ type: 'agent_end', contextUsage });
+        currentText = '';
+        currentTools.length = 0;
+    });
+    pi.on('input', (event, _ctx) => {
+        if (event.source === 'interactive' && typeof event.text === 'string') {
+            history.addUserMessage(event.text);
+            broadcastFn({ type: 'user_message', text: event.text });
+        }
+    });
+}

package/dist/remote/history.d.ts

@@ -0,0 +1,22 @@
+export interface ToolSummary {
+    toolName: string;
+    args: unknown;
+    result: unknown;
+    isError: boolean;
+}
+export interface Turn {
+    role: 'user' | 'assistant';
+    text: string;
+    tools: ToolSummary[];
+    error?: boolean;
+}
+export declare class HistoryBuffer {
+    private entries;
+    private readonly limit;
+    constructor(limit?: number);
+    addUserMessage(text: string): void;
+    addAssistantTurn(text: string, tools: ToolSummary[]): void;
+    addError(text: string): void;
+    getEntries(): Turn[];
+    private _push;
+}

package/dist/remote/history.js

@@ -0,0 +1,25 @@
+export class HistoryBuffer {
+    entries = [];
+    limit;
+    constructor(limit = 20) {
+        this.limit = limit;
+    }
+    addUserMessage(text) {
+        this._push({ role: 'user', text, tools: [] });
+    }
+    addAssistantTurn(text, tools) {
+        this._push({ role: 'assistant', text, tools });
+    }
+    addError(text) {
+        this._push({ role: 'assistant', text, tools: [], error: true });
+    }
+    getEntries() {
+        return [...this.entries];
+    }
+    _push(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > this.limit) {
+            this.entries.shift();
+        }
+    }
+}

package/dist/remote/protocol.d.ts

@@ -0,0 +1,42 @@
+export interface PromptMessage {
+    type: 'prompt';
+    id: string;
+    question: string;
+    recommended?: string;
+    allowSkip: boolean;
+}
+export interface PromptResolvedMessage {
+    type: 'prompt_resolved';
+    id: string;
+}
+export interface WidgetMessage {
+    type: 'widget';
+    key: string;
+    lines: string[] | null;
+}
+export interface NotifyMessage {
+    type: 'notify';
+    message: string;
+    level: 'info' | 'warning' | 'error';
+}
+export interface ViewerMessage {
+    type: 'viewer';
+    title: string;
+    text: string;
+}
+/** Server → browser messages added by the integration. The existing
+ *  history / text_delta / tool_* / agent_* / client_count / user_message messages are
+ *  emitted ad hoc by events.ts / server.ts and are not enumerated here. */
+export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage;
+/** Browser → server messages. */
+export interface ClientChatMessage {
+    type: 'message';
+    text: string;
+}
+export interface ClientPromptAnswer {
+    type: 'prompt_answer';
+    id: string;
+    value: string | undefined;
+}
+export type ClientMessage = ClientChatMessage | ClientPromptAnswer;
+export declare function isClientMessage(x: unknown): x is ClientMessage;

package/dist/remote/protocol.js

@@ -0,0 +1,13 @@
+// Wire format shared by the WS server and the inline browser app.
+// Keep these shapes in sync with the hand-written switch in ui.ts.
+export function isClientMessage(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const m = x;
+    if (m.type === 'message')
+        return typeof m.text === 'string';
+    if (m.type === 'prompt_answer') {
+        return typeof m.id === 'string' && (m.value === undefined || typeof m.value === 'string');
+    }
+    return false;
+}

package/dist/remote/qr.d.ts

@@ -0,0 +1 @@
+export declare function qrLines(url: string): Promise<string[]>;

package/dist/remote/qr.js

@@ -0,0 +1,5 @@
+import qrcode from 'qrcode';
+export async function qrLines(url) {
+    const raw = await qrcode.toString(url, { type: 'terminal', small: true });
+    return raw.split('\n').filter(l => l.length > 0);
+}

package/dist/remote/register.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export declare function registerRemote(pi: ExtensionAPI): void;