pplx-npx-search 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to pplx-cli will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-05-22
+
+### Added
+- **Standard artifacts.** Query-producing commands now save run folders by default with `meta.json`, `query.txt`, `answer.md`, `result.json`, and `sources.json`.
+- **Artifact controls.** `--out <dir>`, `--artifact-id <id>`, and `--no-artifact` support local agent workflows and deterministic run folders.
+- **Perplexity Computer handoff.** `pplx computer` creates artifact-first task prompts for Perplexity Computer and validates `computer-result.json` outputs for local agents.
+
 ## [0.2.2] - 2026-05-21
 
 ### Added
@@ -55,6 +62,7 @@ First public release worth telling people about. (v0.2.0 was unpublished before
 - SSE streaming for real-time answers
 - Optional Playwright and Chrome CDP transports
 
+[0.3.0]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.1.1...v0.2.1
 [0.1.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.1.0...v0.1.1

package/README.md

@@ -101,6 +101,7 @@ pplx search "what is quantum computing"
 pplx reason "explain the Riemann hypothesis"
 pplx research "compare React vs Vue in 2026"
 pplx labs "hello world"          # free, no auth needed
+pplx computer new "compare dinner options nearby"
 pplx models                       # list available models
 ```
 
@@ -145,12 +146,46 @@ pplx search "research this topic" --json --raw --mode pro
   ],
   "query": "...",
   "mode": "pro",
-  "model": "..."
+  "model": "...",
+  "artifactDir": "/Users/you/.config/pplx/artifacts/...",
+  "artifactId": "..."
 }
 ```
 
 ---
 
+## Artifacts
+
+Query-producing commands save artifacts by default:
+
+- `pplx search`
+- `pplx reason`
+- `pplx research`
+- `pplx labs`
+- bare `pplx "query"`
+- `pplx computer new`
+
+Each run gets a folder containing `meta.json`, `query.txt`, `answer.md`, `result.json`, and `sources.json`. Use `--out <dir>` to choose the destination for one run, or set `"artifactDir"` in `~/.config/pplx/config.json` to make it persistent. Use `--artifact-id <id>` when an agent needs a deterministic run folder, and `--no-artifact` to disable saving for one search-style run.
+
+```bash
+pplx search "compare laptops under $1500" --out ~/Dropbox/pplx-runs
+pplx research "best places to stay in Kyoto" --artifact-id kyoto-research
+pplx search "what is 2+2" --no-artifact --json --raw
+```
+
+`pplx computer` is an artifact handoff for Perplexity Computer. It creates a task prompt and a result contract without calling private Computer APIs:
+
+```bash
+pplx computer new "compare dinner options nearby" --out ~/Dropbox/pplx-runs
+pplx computer open <run-id> --copy
+pplx computer status <run-id> --out ~/Dropbox/pplx-runs
+pplx computer import <run-id> --out ~/Dropbox/pplx-runs --json
+```
+
+Computer runs include `task.md`, `result.schema.json`, and `computer-result.json`. Paste `task.md` into Perplexity Computer; when the task is done, place the structured result in `computer-result.json` so local agents can read it.
+
+---
+
 ## Options
 
 | Flag | Description |
@@ -163,6 +198,9 @@ pplx search "research this topic" --json --raw --mode pro
 | `--playwright` | Use Playwright headless Chromium |
 | `--no-playwright` | Force HTTP transport even if config enables Playwright |
 | `--timeout-ms 120000\|120s\|10m` | Overall stream timeout |
+| `--out <dir>` | Directory for saved artifacts |
+| `--artifact-id <id>` | Deterministic artifact id for this run |
+| `--no-artifact` | Disable artifact saving for one search-style run |
 | `--curl` | Force curl-impersonate (auto-downloads if missing) |
 | `--allow-anonymous` | Allow anonymous Perplexity responses when cookies are expired |
 | `--incognito` | Do not save the query to Perplexity history |
@@ -193,7 +231,8 @@ Optional config file at `~/.config/pplx/config.json`:
   "model": "claude-3.5-sonnet",
   "lang": "en-US",
   "playwright": true,
-  "playwrightHeadless": false
+  "playwrightHeadless": false,
+  "artifactDir": "/Users/you/Dropbox/pplx-runs"
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pplx-npx-search",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "CLI for Perplexity AI with cookie-based auth. Headless, agent-friendly, no API key required.",
   "type": "module",
   "bin": {

package/src/artifacts.js

@@ -0,0 +1,85 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { CONFIG_DIR } from './constants.js';
+
+export const DEFAULT_ARTIFACT_DIR = join(CONFIG_DIR, 'artifacts');
+export const ARTIFACT_SCHEMA_VERSION = 1;
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === '~') return homedir();
+  if (value.startsWith('~/')) return join(homedir(), value.slice(2));
+  return value;
+}
+
+export function resolveArtifactDir({ out, config = {} } = {}) {
+  const selected = out || config.artifactDir || DEFAULT_ARTIFACT_DIR;
+  const expanded = expandHome(selected);
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
+}
+
+export function createArtifactId(id) {
+  if (id) {
+    if (!/^[A-Za-z0-9._-]+$/.test(id) || id === '.' || id === '..') {
+      throw new Error('artifact id may only contain letters, numbers, dots, underscores, and hyphens');
+    }
+    return id;
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `${stamp}-${randomUUID().slice(0, 8)}`;
+}
+
+export function makeArtifactContext({ command, query, opts = {}, config = {} }) {
+  if (opts.artifact === false) return null;
+  const artifactId = createArtifactId(opts.artifactId);
+  const artifactRoot = resolveArtifactDir({ out: opts.out, config });
+  const artifactDir = join(artifactRoot, artifactId);
+  return { command, query, artifactId, artifactRoot, artifactDir };
+}
+
+export function writeJson(file, value) {
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function writeStandardArtifact(ctx, payload) {
+  if (!ctx) return null;
+  mkdirSync(ctx.artifactDir, { recursive: true });
+
+  const createdAt = payload.createdAt || new Date().toISOString();
+  const sources = payload.sources || [];
+  const result = {
+    query: ctx.query,
+    answer: payload.answer || '',
+    sources,
+    command: ctx.command,
+    mode: payload.mode || null,
+    model: payload.model || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+  };
+  const meta = {
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    command: ctx.command,
+    query: ctx.query,
+    mode: payload.mode || null,
+    model: payload.model || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: payload.status || 'complete',
+  };
+
+  writeJson(join(ctx.artifactDir, 'meta.json'), meta);
+  writeFileSync(join(ctx.artifactDir, 'query.txt'), `${ctx.query}\n`, 'utf8');
+  writeFileSync(join(ctx.artifactDir, 'answer.md'), payload.answer || '', 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.json'), result);
+  writeJson(join(ctx.artifactDir, 'sources.json'), sources);
+  return { artifactId: ctx.artifactId, artifactDir: ctx.artifactDir };
+}
+
+export function readJsonFile(file) {
+  return JSON.parse(readFileSync(file, 'utf8'));
+}

package/src/cli.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 import { program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
@@ -12,6 +13,15 @@ import { LABS_MODELS, MODEL_MAP } from './constants.js';
 import { setUseCurl } from './http.js';
 import { loadConfig } from './config.js';
 import { resolveTimeoutMs } from './timeout.js';
+import { makeArtifactContext, resolveArtifactDir, writeStandardArtifact } from './artifacts.js';
+import {
+  createComputerRun,
+  copyTextToClipboard,
+  importComputerResult,
+  inspectComputerRun,
+  openComputerUrl,
+  readTaskFile,
+} from './computer.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -93,6 +103,9 @@ program
 program.option('--verbose', 'Enable verbose logging');
 program.option('--proxy <url>', 'Set proxy URL (sets HTTPS_PROXY env var)');
 program.option('--raw', 'Plain text output, no colors, no spinner');
+program.option('--out <dir>', 'Directory for saved artifacts');
+program.option('--no-artifact', 'Disable artifact saving for this run');
+program.option('--artifact-id <id>', 'Deterministic artifact id for this run');
 
 program.hook('preAction', (thisCmd) => {
   const gopts = thisCmd.optsWithGlobals ? thisCmd.optsWithGlobals() : thisCmd.opts();
@@ -107,6 +120,35 @@ program.hook('preAction', (thisCmd) => {
   }
 });
 
+function getOpts(commandOrOpts) {
+  const globals = program.opts();
+  const locals = commandOrOpts.optsWithGlobals
+    ? { ...commandOrOpts.optsWithGlobals(), ...commandOrOpts.opts() }
+    : commandOrOpts;
+  const merged = { ...globals, ...locals };
+  if (globals.artifact === false || locals.artifact === false) merged.artifact = false;
+  return merged;
+}
+
+function addArtifactOptions(command, { allowDisable = true } = {}) {
+  command
+    .option('--out <dir>', 'Directory for saved artifacts')
+    .option('--artifact-id <id>', 'Deterministic artifact id for this run');
+  if (allowDisable) command.option('--no-artifact', 'Disable artifact saving for this run');
+  return command;
+}
+
+function maybePrintArtifactInfo(info, opts) {
+  if (!info || opts.json || rawMode) return;
+  console.log(chalk.dim(`\nArtifact: ${info.artifactDir}`));
+}
+
+function resolveRunDir(runId, opts = {}) {
+  if (isAbsolute(runId) || runId.includes('/')) return resolve(runId);
+  const cfg = loadConfig();
+  return join(resolveArtifactDir({ out: opts.out, config: cfg }), runId);
+}
+
 // Auth command
 program
   .command('auth')
@@ -259,9 +301,9 @@ program
   });
 
 // Shared search logic
-async function doSearch(query, opts) {
+async function doSearch(query, opts, commandName = 'search') {
   const cfg = loadConfig();
-  opts = { ...cfg, ...opts };
+  opts = { ...cfg, ...getOpts(opts) };
   if (opts.curl) setUseCurl(true);
 
   const cookies = loadCookies() || {};
@@ -287,6 +329,13 @@ async function doSearch(query, opts) {
   }
   const sources = opts.sources ? opts.sources.split(',') : ['web'];
   const lang = opts.lang || 'en-US';
+  let artifactCtx = null;
+  try {
+    artifactCtx = makeArtifactContext({ command: commandName, query, opts, config: cfg });
+  } catch (e) {
+    console.error(chalk.red(e.message));
+    process.exit(1);
+  }
 
   try {
     let lastAnswer = '';
@@ -325,12 +374,21 @@ async function doSearch(query, opts) {
       // Output single final JSON object
       const answer = lastData?.answer || lastAnswer || '';
       const webResults = lastData?.web_results || [];
+      const normalizedSources = webResults.map(r => ({ title: r.name || r.title, url: r.url }));
+      const artifactInfo = writeStandardArtifact(artifactCtx, {
+        answer,
+        sources: normalizedSources,
+        mode,
+        model: opts.model || 'default',
+      });
       const jsonOut = {
         answer,
-        sources: webResults.map(r => ({ title: r.name || r.title, url: r.url })),
+        sources: normalizedSources,
         query,
         mode,
         model: opts.model || 'default',
+        artifactDir: artifactInfo?.artifactDir,
+        artifactId: artifactInfo?.artifactId,
       };
       console.log(JSON.stringify(jsonOut));
       if (!answer) process.exit(1);
@@ -347,6 +405,14 @@ async function doSearch(query, opts) {
     if (!rawMode && opts.citations !== false && lastData?.web_results) {
       console.log(formatSources(lastData.web_results, { full: opts.citationsFull }));
     }
+    const webResults = lastData?.web_results || [];
+    const artifactInfo = writeStandardArtifact(artifactCtx, {
+      answer: lastAnswer,
+      sources: webResults.map(r => ({ title: r.name || r.title, url: r.url })),
+      mode,
+      model: opts.model || 'default',
+    });
+    maybePrintArtifactInfo(artifactInfo, opts);
   } catch (e) {
     console.error(chalk.red('\nError:'), e.message);
     if (e.message.includes('403')) {
@@ -357,7 +423,7 @@ async function doSearch(query, opts) {
 }
 
 // Search command
-program
+addArtifactOptions(program
   .command('search [query]')
   .description('Search with Perplexity (default: pro mode)')
   .option('-m, --mode <mode>', 'Search mode: auto, pro, reasoning, deep-research', 'pro')
@@ -374,15 +440,16 @@ program
   .option('--playwright', 'Use Playwright headless Chromium instead of HTTP')
   .option('--no-playwright', 'Disable Playwright even if config enables it')
   .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
-  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired'))
   .action(async (queryArg, opts) => {
+    opts = getOpts(opts);
     if (opts.raw) { rawMode = true; chalk.level = 0; }
     const query = await resolveQuery(queryArg);
-    await doSearch(query, opts);
+    await doSearch(query, opts, 'search');
   });
 
 // Shorthand: reason
-program
+addArtifactOptions(program
   .command('reason [query]')
   .description('Reasoning mode search')
   .option('--model <model>', 'Model name')
@@ -392,14 +459,15 @@ program
   .option('--playwright', 'Use Playwright headless Chromium')
   .option('--no-playwright', 'Disable Playwright even if config enables it')
   .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
-  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired'))
   .action(async (queryArg, opts) => {
+    opts = getOpts(opts);
     const query = await resolveQuery(queryArg);
-    await doSearch(query, { ...opts, mode: 'reasoning' });
+    await doSearch(query, { ...opts, mode: 'reasoning' }, 'reason');
   });
 
 // Shorthand: research
-program
+addArtifactOptions(program
   .command('research [query]')
   .description('Deep research mode')
   .option('--json', 'Output raw JSON')
@@ -408,12 +476,13 @@ program
   .option('--playwright', 'Use Playwright headless Chromium')
   .option('--no-playwright', 'Disable Playwright even if config enables it')
   .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
-  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired'))
   .action(async (queryArg, opts) => {
+    opts = getOpts(opts);
     const query = await resolveQuery(queryArg);
     const spinner = makeSpinner('Deep research in progress...').start();
     try {
-      await doSearch(query, { ...opts, mode: 'deep-research', _spinner: spinner });
+      await doSearch(query, { ...opts, mode: 'deep-research', _spinner: spinner }, 'research');
     } catch (e) {
       spinner.fail(e.message);
       process.exit(1);
@@ -421,13 +490,22 @@ program
   });
 
 // Labs command
-program
+addArtifactOptions(program
   .command('labs [query]')
   .description('Query open-source models (no auth needed)')
   .option('--model <model>', `Model: ${LABS_MODELS.join(', ')}`, 'sonar')
-  .option('--json', 'Output raw JSON')
+  .option('--json', 'Output single JSON object with answer, events, and artifact metadata'))
   .action(async (queryArg, opts) => {
+    opts = getOpts(opts);
+    const cfg = loadConfig();
     const query = await resolveQuery(queryArg);
+    let artifactCtx = null;
+    try {
+      artifactCtx = makeArtifactContext({ command: 'labs', query, opts, config: cfg });
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
     const spinner = makeSpinner('Connecting to labs...').start();
     const client = new LabsClient();
     try {
@@ -435,9 +513,10 @@ program
       spinner.stop();
 
       let lastOutput = '';
+      const events = [];
       for await (const data of client.ask(query, opts.model)) {
+        events.push(data);
         if (opts.json) {
-          console.log(JSON.stringify(data));
           continue;
         }
         const output = data.output || '';
@@ -447,14 +526,129 @@ program
         }
       }
       if (!opts.json) process.stdout.write('\n');
+      const artifactInfo = writeStandardArtifact(artifactCtx, {
+        answer: lastOutput,
+        sources: [],
+        mode: 'labs',
+        model: opts.model,
+      });
+      if (opts.json) {
+        console.log(JSON.stringify({
+          answer: lastOutput,
+          events,
+          query,
+          mode: 'labs',
+          model: opts.model,
+          artifactDir: artifactInfo?.artifactDir,
+          artifactId: artifactInfo?.artifactId,
+        }));
+      } else {
+        maybePrintArtifactInfo(artifactInfo, opts);
+      }
     } catch (e) {
       spinner.fail('Labs error: ' + e.message);
+      if (isQuiet()) console.error(chalk.red('Labs error:'), e.message);
       process.exit(1);
     } finally {
       client.close();
     }
   });
 
+// Computer artifact handoff workflow
+const computer = program
+  .command('computer')
+  .description('Create and manage Perplexity Computer artifact handoffs');
+
+addArtifactOptions(computer
+  .command('new [task]')
+  .description('Create a Perplexity Computer task artifact')
+  .option('--template <name>', 'Computer task template', 'compare')
+  .option('--json', 'Output run metadata as JSON'), { allowDisable: false })
+  .action(async (taskArg, opts) => {
+    opts = getOpts(opts);
+    const task = await resolveQuery(taskArg);
+    try {
+      const run = createComputerRun({
+        task,
+        template: opts.template,
+        opts,
+        config: loadConfig(),
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(run));
+        return;
+      }
+      console.log(chalk.green(`✓ Computer task artifact created: ${run.artifactDir}`));
+      console.log(chalk.dim(`  Task: ${run.taskPath}`));
+      console.log(chalk.dim(`  Result: ${run.resultPath}`));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(computer
+  .command('open <run>')
+  .description('Open Perplexity Computer and optionally copy task.md')
+  .option('--copy', 'Copy task.md to the clipboard'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const runDir = resolveRunDir(runId, opts);
+    try {
+      if (opts.copy) {
+        const taskText = readTaskFile(runDir);
+        if (!copyTextToClipboard(taskText)) {
+          console.log(chalk.yellow('Clipboard copy is only supported on macOS.'));
+        }
+      }
+      if (!openComputerUrl()) {
+        console.log(chalk.yellow('Opening Perplexity Computer is only supported on macOS.'));
+        console.log('https://www.perplexity.ai/computer');
+        return;
+      }
+      console.log(chalk.green(`✓ Opened Perplexity Computer for ${runDir}`));
+      if (opts.copy) console.log(chalk.dim('  Copied task.md to clipboard.'));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(computer
+  .command('status <run>')
+  .description('Inspect a Perplexity Computer artifact run')
+  .option('--json', 'Output status as JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const status = inspectComputerRun(resolveRunDir(runId, opts));
+    if (opts.json) {
+      console.log(JSON.stringify(status));
+      return;
+    }
+    const label = status.status === 'complete'
+      ? chalk.green('[✓] Complete')
+      : status.status === 'pending'
+        ? chalk.yellow('[○] Pending')
+        : chalk.red(status.status === 'invalid' ? '[!] Invalid' : '[✗] Missing');
+    console.log(`${label} ${status.artifactDir}`);
+    if (status.reason) console.log(chalk.dim(`  ${status.reason}`));
+  });
+
+addArtifactOptions(computer
+  .command('import <run>')
+  .description('Print a completed Perplexity Computer result')
+  .option('--json', 'Output compact JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    try {
+      const result = importComputerResult(resolveRunDir(runId, opts));
+      console.log(opts.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
 // Models command
 program
   .command('models')
@@ -472,9 +666,9 @@ program
 // Default: treat bare args as search
 program
   .argument('[query...]', 'Quick search (shorthand for pplx search)')
-  .action(async (query) => {
+  .action(async (query, opts) => {
     if (query.length > 0) {
-      await doSearch(query.join(' '), {});
+      await doSearch(query.join(' '), getOpts(opts || program), 'search');
     }
   });
 

package/src/computer.js

@@ -0,0 +1,193 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  ARTIFACT_SCHEMA_VERSION,
+  makeArtifactContext,
+  readJsonFile,
+  writeJson,
+} from './artifacts.js';
+
+export const COMPUTER_URL = 'https://www.perplexity.ai/computer';
+export const COMPUTER_RESULT_FILE = 'computer-result.json';
+export const PENDING_COMPUTER_RESULT = {
+  summary: '',
+  winner: '',
+  confidence: 'low',
+  items: [],
+  sources: [],
+  checked_at: '',
+  notes: [],
+  _status: 'pending',
+};
+
+const RESULT_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'pplx computer comparison result',
+  type: 'object',
+  required: ['summary', 'winner', 'confidence', 'items', 'sources', 'checked_at', 'notes'],
+  properties: {
+    summary: { type: 'string' },
+    winner: { type: 'string' },
+    confidence: { enum: ['low', 'medium', 'high'] },
+    items: { type: 'array' },
+    sources: { type: 'array' },
+    checked_at: { type: 'string' },
+    notes: { type: 'array' },
+  },
+};
+
+export function buildComputerTask({ task, template = 'compare', resultPath }) {
+  if (template !== 'compare') {
+    throw new Error(`unsupported computer template: ${template}`);
+  }
+
+  return `# Perplexity Computer Task
+
+You are running a live comparison task for a local agent workflow.
+
+## User request
+
+${task}
+
+## Instructions
+
+- Use live web pages and direct source pages where possible, not only search snippets.
+- Compare any relevant prices, fees, availability, location, timing, quality signals, eligibility rules, and constraints.
+- This template is intentionally broad: it can cover products, real estate, restaurants, food prices, travel, rewards portals, services, and other comparison tasks.
+- Preserve source URLs for every material claim.
+- Include the time the information was checked.
+- Mark uncertainty explicitly. Do not invent missing values.
+- Prefer structured evidence over prose.
+
+## Output target
+
+Write the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+export function createComputerRun({ task, template = 'compare', opts = {}, config = {} }) {
+  const ctx = makeArtifactContext({ command: 'computer', query: task, opts, config });
+  if (!ctx) {
+    throw new Error('computer runs require artifacts; omit --no-artifact for this command');
+  }
+
+  mkdirSync(ctx.artifactDir, { recursive: true });
+  const createdAt = new Date().toISOString();
+  const resultPath = join(ctx.artifactDir, COMPUTER_RESULT_FILE);
+  const taskText = buildComputerTask({ task, template, resultPath });
+  const meta = {
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    command: 'computer',
+    query: task,
+    template,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+  };
+  const result = {
+    query: task,
+    answer: '',
+    sources: [],
+    command: 'computer',
+    mode: 'computer',
+    model: null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+    computerResultFile: COMPUTER_RESULT_FILE,
+  };
+
+  writeJson(join(ctx.artifactDir, 'meta.json'), meta);
+  writeFileSync(join(ctx.artifactDir, 'query.txt'), `${task}\n`, 'utf8');
+  writeFileSync(join(ctx.artifactDir, 'answer.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.json'), result);
+  writeJson(join(ctx.artifactDir, 'sources.json'), []);
+  writeFileSync(join(ctx.artifactDir, 'task.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.schema.json'), RESULT_SCHEMA);
+  writeJson(resultPath, PENDING_COMPUTER_RESULT);
+
+  return {
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    taskPath: join(ctx.artifactDir, 'task.md'),
+    resultPath,
+  };
+}
+
+function assertComputerResult(value) {
+  const missing = ['summary', 'winner', 'confidence', 'items', 'sources', 'checked_at', 'notes']
+    .filter((key) => !(key in value));
+  if (missing.length) return { ok: false, reason: `missing fields: ${missing.join(', ')}` };
+  if (!['low', 'medium', 'high'].includes(value.confidence)) {
+    return { ok: false, reason: 'confidence must be low, medium, or high' };
+  }
+  if (!Array.isArray(value.items)) return { ok: false, reason: 'items must be an array' };
+  if (!Array.isArray(value.sources)) return { ok: false, reason: 'sources must be an array' };
+  if (!Array.isArray(value.notes)) return { ok: false, reason: 'notes must be an array' };
+  return { ok: true, reason: null };
+}
+
+export function inspectComputerRun(runDir) {
+  const artifactDir = resolve(runDir);
+  const resultPath = join(artifactDir, COMPUTER_RESULT_FILE);
+  const metaPath = join(artifactDir, 'meta.json');
+  if (!existsSync(metaPath)) {
+    return { status: 'missing', artifactDir, resultPath, reason: 'meta.json not found' };
+  }
+  if (!existsSync(resultPath)) {
+    return { status: 'pending', artifactDir, resultPath, reason: `${COMPUTER_RESULT_FILE} not found` };
+  }
+  try {
+    const result = readJsonFile(resultPath);
+    if (result._status === 'pending') {
+      return { status: 'pending', artifactDir, resultPath, reason: `${COMPUTER_RESULT_FILE} is still pending` };
+    }
+    const validation = assertComputerResult(result);
+    return {
+      status: validation.ok ? 'complete' : 'invalid',
+      artifactDir,
+      resultPath,
+      reason: validation.reason,
+      result,
+    };
+  } catch (e) {
+    return { status: 'invalid', artifactDir, resultPath, reason: e.message };
+  }
+}
+
+export function importComputerResult(runDir) {
+  const status = inspectComputerRun(runDir);
+  if (status.status !== 'complete') {
+    throw new Error(`computer result is ${status.status}: ${status.reason}`);
+  }
+  return status.result;
+}
+
+export function copyTextToClipboard(text) {
+  if (process.platform === 'darwin') {
+    execFileSync('pbcopy', { input: text });
+    return true;
+  }
+  return false;
+}
+
+export function openComputerUrl() {
+  if (process.platform === 'darwin') {
+    execFileSync('open', [COMPUTER_URL]);
+    return true;
+  }
+  return false;
+}
+
+export function readTaskFile(runDir) {
+  return readFileSync(join(resolve(runDir), 'task.md'), 'utf8');
+}

package/src/labs.js

@@ -45,6 +45,9 @@ export class LabsClient {
       headers: { 'user-agent': HEADERS['user-agent'] },
     });
     const pollText = await pollResp.text();
+    if (!pollResp.ok) {
+      throw new Error(`Labs polling failed (${pollResp.status}): ${pollText.slice(0, 120)}`);
+    }
 
     const handshake = parseEngineIO(pollText);
     this.sid = handshake.sid;