@aipoch/open-science 1.0.1 → 1.0.3

package/CLI.md

@@ -8,7 +8,29 @@ defines the 1.x contract for commands, machine-readable output and exit codes.
 
 ## Installation
 
-### Standalone Node package
+### From npm
+
+Install the published [standalone CLI](https://www.npmjs.com/package/@aipoch/open-science)
+with Node.js **22.13.0 or later**:
+
+```bash
+npm install --global @aipoch/open-science
+open-science start --no-open
+open-science url
+```
+
+The registry package installs the matching native backend, Web UI and resources through npm
+optional dependencies. It runs without Electron or an installed desktop app. Supported targets
+are macOS ARM64/x64, glibc Linux ARM64/x64 and Windows x64; musl Linux and Windows ARM64 are not
+supported. Do not omit optional dependencies. If startup reports a missing native package, run
+`npm install --global @aipoch/open-science --include=optional`.
+
+Open the printed authenticated URL to configure an Agent runtime, model provider and optional
+Python/R Notebook runtime, or follow [First-run setup (Codex)](#first-run-setup-codex) from the
+terminal. See the [standalone runtime guide](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md#linux-prerequisites)
+for Linux credential storage and sandbox prerequisites.
+
+### Locally built standalone tarball
 
 Install the target-specific standalone tarball built with `npm run pack:backend`, using ordinary
 Node >=22.13.0. It includes the backend, Web UI, resources and native dependencies; Electron and
@@ -54,25 +76,58 @@ not require a separate Node.js installation.
 If the launcher directory is not yet on PATH, the Settings panel shows the line to add. Open a new
 terminal after updating PATH. Choose **Uninstall command** in the same panel to remove the launcher.
 
-### From npm
+### From a source checkout
 
-The lightweight CLI/SDK package requires Node.js 22.5 or later. It controls an existing service.
-To start an independent service, install the standalone artifact (Node >=22.13.0); the lightweight
-package alone does not contain backend resources.
-Install it globally after the package is published:
+Replace `open-science` in the examples below with:
 
 ```bash
-npm install --global @aipoch/open-science
-open-science --help
+node packages/open-science/cli.mjs
 ```
 
-### From a source checkout
+## Local information and help
 
-Replace `open-science` in the examples below with:
+These commands work without starting or connecting to the service:
 
 ```bash
-node packages/open-science/cli.mjs
-```
+open-science --version
+open-science -v
+open-science version --json
+open-science help
+open-science help run
+open-science paths --json
+open-science paths --profile /absolute/path/to/profile
+```
+
+`--version`, `-v`, and `version` print the invoked CLI's application version, including any
+nightly suffix. `version --json` prints `{ "version": "..." }`. Source checkouts use the root
+application version; installed distributions use their own release metadata. This is not the
+version of a running service. The version flags are standalone commands, not options for `run`,
+`start`, or other commands.
+
+`help` is equivalent to `--help`; `help <command>` is equivalent to `<command> --help`.
+For example, `help project` lists Project commands. Unknown command names and unsupported
+arguments fail with the existing usage-error exit code `2`.
+
+`paths` prints human-readable locations; `paths --json` prints one object with:
+
+| Field                  | Meaning                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `cliPath`              | The CLI implementation file used by this invocation.                                     |
+| `nodePath`             | The Node executable running the CLI.                                                     |
+| `startupConfigRoot`    | The configuration directory selected by the installation's default or explicit override. |
+| `discoveryConfigRoots` | Ordered candidate configuration directories searched for an existing service.            |
+
+Source checkouts default to `~/.open-science-project` for startup; installations default to
+`~/.open-science`. Without an override, service discovery checks the development directory first,
+then the production directory. `--config-root` (or `--profile`) takes precedence over
+`OPEN_SCIENCE_CONFIG_ROOT`, then `OPEN_SCIENCE_STORAGE_ROOT`; an override selects a single
+absolute directory for both startup and discovery. Paths are reported even when they do not exist.
+The output does not identify an active service or a research-data directory, which may differ.
+
+These commands do not create profiles, modify settings, read credentials, or print authenticated
+URLs. Successful queries exit `0`; missing or invalid version metadata produces an error rather
+than a fallback version. `paths` accepts only the profile, JSON, and help options; `version`
+accepts only JSON and help options, and `help` accepts only one optional command name and help flags.
 
 ## Service lifecycle
 
@@ -106,7 +161,7 @@ open-science url
 `open-science url` is the only command that intentionally prints an authenticated browser URL. Normal
 human-readable, JSON, and JSONL output never includes the local token.
 
-Use `--port <port>` to override `OPEN_SCIENCE_WEB_PORT`, or the default port of `44100` when neither is set. `start` discovers the standalone
+Use `--port <port>` to override `OPEN_SCIENCE_WEB_PORT`, or the default port of `44100` when neither is set. `start` discovers the matching npm platform package, the standalone
 Node entry bundled beside the CLI, or `out/backend/index.cjs` in a source checkout. Build the
 source entry with `npm run build:backend` and Web UI with `npm run build:web` first.
 `--app-path` and `OPEN_SCIENCE_APP_PATH` no longer select a hidden Electron backend.
@@ -166,7 +221,7 @@ nonzero CLI error codes.
 
 ## First-run setup (Codex)
 
-Install the standalone artifact or a desktop package containing the ordinary Node backend first.
+Install the npm package, a standalone artifact or a desktop package containing the ordinary Node backend first.
 `init` creates a configuration directory only; `--profile` selects an absolute configuration directory.
 
 ```bash
@@ -249,9 +304,23 @@ open-science runtime list --json
 ## Upgrading installations
 
 Stop the backend before upgrading an installation, then restart it with the same profile.
+For a global npm installation:
+
+```bash
+open-science stop
+npm install --global @aipoch/open-science@latest
+open-science start --no-open
+```
+
+Stop every profile started by that installation before updating it; use `--config-root` for
+custom profiles. To uninstall, stop those services and run
+`npm uninstall --global @aipoch/open-science`. Research data and credentials are retained.
+See [release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md)
+before downgrading; reinstalling an older package does not undo data migrations.
+
 Use the installation channel that owns the CLI: Homebrew for a Formula, the new downloaded
 package for deb/rpm or a local npm tarball, or a verified new Release archive in a new directory
-with PATH/the symlink updated. npm registry publication remains deferred.
+with PATH/the symlink updated.
 The desktop update UI discovers and downloads packages. Automatic replacement remains closed for
 macOS ZIP, Linux AppImage and Debian until each channel passes complete installed-package
 acceptance. Windows automatic installation remains disabled; artifact checks and same-version copy tests do not certify a cross-version upgrade.
@@ -537,6 +606,43 @@ turns only and is rejected while root-agent, subagent, or Notebook work is activ
 does not block the update. Stale revisions fail with `session_revision_conflict`; invalid or
 unavailable references fail with `invalid_configuration`.
 
+## Session package export and import
+
+Export a Session to a `.science` package at an explicit path. The Session must be idle:
+
+```bash
+open-science session export <session-id> --project <id-or-name> --output ~/backups/session.science
+```
+
+`--project` resolves a Project by id or name and selects which Session to export. `--output` must
+be an absolute or relative path ending in `.science`; when it is omitted the command fails instead
+of opening a native save dialog, because the CLI runs without a desktop session. The command
+returns the saved status and written path as JSON with `--json`.
+
+Both package commands allow up to one hour by default. Use `--timeout-ms <milliseconds>`
+to adjust the request deadline for large packages or slower disks.
+
+Import a `.science` package. Import is non-interactive by design and requires an explicit
+confirmation flag:
+
+```bash
+open-science session import ~/backups/session.science --new-project "Restored session" --non-interactive
+open-science session import ~/backups/session.science --project <id-or-name> --non-interactive
+```
+
+`--non-interactive` confirms the import preview on the caller's behalf; without it the command
+fails rather than waiting for an approval that a headless caller can never supply. Choose exactly
+one destination: `--project` imports into an existing Project, `--new-project` creates one with
+the given name, and omitting both uses the package's own Project name in a new Project. The
+package file is read directly from disk, so no upload or drag-and-drop step is involved.
+
+Both commands dispatch the same `sessions:export-package`, `sessions:import-package`, and
+`sessions:package-operation` application commands the desktop app uses, over the authenticated
+loopback HTTP channel. They are unavailable to remote Web sessions by design: the channel is
+installed as a rejecting stub for remote callers, and the handler additionally requires a local
+caller, so arbitrary-path file read and write stay confined to loopback callers that hold the
+service token.
+
 ## Agent routing settings
 
 Inspect or atomically update the global Agent framework plus Reviewer and Subagent model routing:

package/README.md

@@ -1,10 +1,88 @@
 # @aipoch/open-science
 
-Node.js SDK and command-line client for an Open-Science daemon running on the local machine.
+[AIPOCH Open-Science](https://github.com/aipoch/open-science) is an open-source, local-first,
+model-agnostic AI research workbench. Use scientific Agents, Python and R Notebooks, and
+scientific data connectors to turn research questions into reports, tables and figures.
+
+This package provides the **standalone CLI, local Web UI and Node.js SDK**. npm installs the
+matching platform package with the backend and resources; the desktop app is not required.
+
+## Install
+
+Install [Node.js](https://nodejs.org/) **22.13.0 or later**, then run:
+
+```bash
+npm install --global @aipoch/open-science
+open-science --help
+```
+
+Supported platforms are macOS Apple Silicon/Intel, Linux ARM64/x64 with glibc, and Windows x64.
+Linux musl (including Alpine) and Windows ARM64 are not supported by the published native packages.
+Keep npm optional dependencies enabled: they contain the platform runtime. If startup reports a
+missing native package, reinstall with `npm install --global @aipoch/open-science --include=optional`.
+
+Linux also needs working credential storage and Notebook sandbox prerequisites; see the
+[Linux setup requirements](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md#linux-prerequisites).
+Python/R and an Agent runtime/model provider are configured separately during setup.
+For installations that include Node itself, see the
+[Homebrew and Release archive options](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md).
+
+## Get started
+
+Start the local service and request its browser URL:
+
+```bash
+open-science start --no-open
+open-science url
+```
+
+Open the printed URL, complete the setup checks, configure an Agent runtime and model provider,
+and create your first research project. Set up a Python or R Notebook runtime if your work needs
+code execution. The URL contains a local authentication token; keep it private.
+For setup from the terminal, follow the
+[CLI first-run guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md#first-run-setup-codex).
+
+After setup, submit a task from the terminal:
+
+```bash
+open-science doctor --json
+open-science project create "First research" --json
+open-science run --project "First research" --prompt "Draft a research plan for comparing two analysis methods." --wait --jsonl
+```
+
+Confirm `ready: true` in the doctor output before submitting work. The CLI accepts a Project ID
+or an exact, unambiguous name; SDK calls use IDs. Closing the browser does not stop the service:
+
+```bash
+open-science status --json
+open-science stop
+```
+
+Stopping the service affects all connected clients. For automated tasks, review the
+[permissions and output options](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md)
+and the safety guidance below.
+
+## Update or uninstall
+
+Stop services started by this installation before replacing it. Use the same `--config-root`
+when stopping and restarting a custom profile.
+
+```bash
+open-science stop
+npm install --global @aipoch/open-science@latest
+open-science start --no-open
+```
+
+To uninstall, stop the service and run `npm uninstall --global @aipoch/open-science`.
+Uninstalling the npm package retains research data and credentials. Review
+[release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md)
+before changing versions; replacing program files does not reverse data migrations.
 
 ## Documentation
 
-- [CLI guide](./CLI.md) - installation, daemon lifecycle, task automation, artifacts, and exit codes
+- [CLI guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md) - installation, daemon lifecycle, task automation, artifacts, and exit codes
+- [Product overview](https://github.com/aipoch/open-science#readme) - research workflows, screenshots and desktop downloads
+- [Report an issue](https://github.com/aipoch/open-science/issues) - bugs and feature requests
 - [Release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md) - stable interfaces, versioning, and data upgrades
 - [Intended use](https://github.com/aipoch/open-science/blob/main/docs/usage-scope.md) and [known limitations](https://github.com/aipoch/open-science/blob/main/docs/known-limitations.md) - workflow precautions, data disclosure, and execution boundaries
 
@@ -25,19 +103,28 @@ Node.js SDK and command-line client for an Open-Science daemon running on the lo
 ## Browser-held package import
 
 Use `@aipoch/open-science/browser-import` to send a downloaded `.science` Blob to the desktop app.
-See the [browser integration guide](./BROWSER_IMPORT.md) for the click flow, API, security contract,
+See the [browser integration guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/BROWSER_IMPORT.md) for the click flow, API, security contract,
 limits, and browser requirements. The desktop never downloads the online package URL.
 
 ## SDK quick start
 
+Install the package in your Node.js project (a global CLI install does not make it importable):
+
+```bash
+npm install @aipoch/open-science
+```
+
+Start and configure the local service as above. Save the example in an `.mjs` file and run it
+with Node.js. It creates a Project and uses its ID for subsequent requests:
+
 ```js
 import { connectToOpenScience } from '@aipoch/open-science'
 
 const client = await connectToOpenScience()
+const project = await client.createProject({ name: 'Evidence review' })
 const run = await client.startRun({
-  project: '<project-id-or-exact-name>',
+  project: project.id,
   prompt: 'Summarize the evidence.',
-  cwd: '/absolute/path/to/research',
   permissionProfile: 'auto',
   permissionPrompts: 'none' // Deny requests that would require a human; keep existing permission rules.
 })
@@ -55,8 +142,8 @@ await client.updateSessionConfiguration(run.sessionId, {
   memoryEnabled: false
 })
 
-const defaults = await client.getProjectSessionDefaults('systematic-review')
-await client.updateProjectSessionDefaults('systematic-review', {
+const defaults = await client.getProjectSessionDefaults(project.id)
+await client.updateProjectSessionDefaults(project.id, {
   expectedUpdatedAt: defaults.updatedAt,
   patch: { permissionProfile: 'auto' }
 })
@@ -142,7 +229,7 @@ const progress = (async () => {
 })()
 
 const observedRun = await client.startRun({
-  project: '<project-id-or-exact-name>',
+  project: project.id,
   prompt: 'Summarize the evidence.',
   permissionProfile: 'auto'
 })

package/browser-import.d.ts

@@ -36,6 +36,8 @@ export function checkBrowserImportAvailability(
 export type BrowserImportTransfer = {
   /** Contains a secret; never log or persist it. Browser policy may require a fresh user click. */
   readonly url: string
+  /** Abort requests and timers, invalidate this transfer, and best-effort cancel the receiver. */
+  cancel(): Promise<void>
   /** Acknowledges receipt only, independently of destination selection and final import consent.
    * Authenticated desktop cancellation throws code 'cancelled', terminal for this transfer.
    * Keep the Blob and explicitly prepare a new transfer; never automatically retry cancellation. */
@@ -46,16 +48,20 @@ export type BrowserImportTransfer = {
     onPhase?: (phase: BrowserImportPhase) => void
     /** Acknowledged bytes only; first callback follows the first successful chunk acknowledgment. */
     onProgress?: (progress: BrowserImportProgress) => void
-    /** Default attempts preserves the 1–5 attempt limit. wait-for-launch retries until the
+    /** Default attempts preserves the 1–30 attempt limit. wait-for-launch retries until the
      * overall deadline or cancellation; it observes only this transfer's authenticated handshake. */
     readinessMode?: BrowserImportReadinessMode
     /** Readiness only; defaults to 120,000 ms. Capped at 120,000 ms in wait-for-launch,
-     * 300,000 ms in attempts mode. Timeout permits another send() on the same live transfer. */
-    readyTimeoutMs?: number
-    /** 1–5 attempts with 1,000 ms gaps; defaults to 5. Ignored in wait-for-launch mode. */
+     * 300,000 ms in attempts mode. Set null only in attempts mode to stop by attempt count
+     * without an overall deadline (including across page suspension). Per-request timeouts
+     * still apply. Timeout/exhaustion permits another send() on the same live transfer. */
+    readyTimeoutMs?: number | null
+    /** 1–30 attempts with 1,000 ms gaps; defaults to 5. Ignored in wait-for-launch mode. */
     readinessAttempts?: number
+    /** Delay after each failed attempt; defaults to 1,000 ms. Range: 0–30,000 ms. */
+    readinessIntervalMs?: number
     /** Includes response body reads; defaults to 2,000 ms. Accepts up to 30,000 ms,
-     * clamped to 2,000 ms in wait-for-launch mode. Failed attempts have 1,000 ms gaps. */
+     * clamped to 2,000 ms in wait-for-launch mode. Failed attempts use readinessIntervalMs. */
     attemptTimeoutMs?: number
   }): Promise<{ received: true }>
 }

package/browser-import.mjs

@@ -178,9 +178,33 @@ export function prepareBrowserImport(file, options = {}) {
   let sending = false
   let received = false
   let cancelled
+  const lifetime = new AbortController()
+  let cancellation
+  // Cancel this secret-bound receiver even while readiness is still pending.
+  const cancel = () => {
+    if (received) return Promise.resolve()
+    if (cancellation) return cancellation
+    cancelled = new BrowserImportError('cancelled', 'The transfer was cancelled.')
+    lifetime.abort(cancelled)
+    cancellation = bounded(undefined, 2000, async (signal) => {
+      const headers = await authorize('DELETE', '')
+      signal.throwIfAborted()
+      await fetch(base, {
+        method: 'DELETE',
+        mode: 'cors',
+        credentials: 'omit',
+        redirect: 'error',
+        headers,
+        signal,
+        targetAddressSpace: 'loopback'
+      })
+    }).catch(() => undefined)
+    return cancellation
+  }
 
   return Object.freeze({
     url,
+    cancel,
     async send({
       signal,
       onProgress,
@@ -188,18 +212,23 @@ export function prepareBrowserImport(file, options = {}) {
       readinessMode = 'attempts',
       readyTimeoutMs = 120_000,
       readinessAttempts = 5,
+      readinessIntervalMs = 1000,
       attemptTimeoutMs = 2000
     } = {}) {
       if (!['attempts', 'wait-for-launch'].includes(readinessMode))
         throw new Error('Invalid readiness mode.')
       const waitingForLaunch = readinessMode === 'wait-for-launch'
-      if (!Number.isFinite(readyTimeoutMs) || readyTimeoutMs <= 0)
+      const countOnly = !waitingForLaunch && readyTimeoutMs === null
+      if (!countOnly && (!Number.isFinite(readyTimeoutMs) || readyTimeoutMs <= 0))
         throw new Error('Invalid receiver timeout.')
       if (
         (!waitingForLaunch &&
           (!Number.isInteger(readinessAttempts) ||
             readinessAttempts < 1 ||
-            readinessAttempts > 5)) ||
+            readinessAttempts > 30)) ||
+        !Number.isFinite(readinessIntervalMs) ||
+        readinessIntervalMs < 0 ||
+        readinessIntervalMs > 30_000 ||
         !Number.isFinite(attemptTimeoutMs) ||
         attemptTimeoutMs <= 0 ||
         attemptTimeoutMs > 30_000
@@ -208,49 +237,54 @@ export function prepareBrowserImport(file, options = {}) {
       if (sending) throw new Error('This browser transfer is already running.')
       if (cancelled) throw cancelled
       if (received) return { received: true }
-      signal?.throwIfAborted()
+      signal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal
+      signal.throwIfAborted()
       sending = true
       let verified = false
-      const request = async (path, init = {}) => {
-        const response = await fetch(base + path, {
-          mode: 'cors',
-          credentials: 'omit',
-          cache: 'no-store',
-          redirect: 'error',
-          targetAddressSpace: 'loopback',
-          ...init,
-          signal: AbortSignal.any(
-            [signal, init.signal ?? AbortSignal.timeout(30_000)].filter(Boolean)
-          )
-        })
-        if (response.status === 410) {
-          const value = await response.json().catch(() => {
-            throw new BrowserImportError(
-              'incompatible',
-              'Could not verify the local receiver identity.'
-            )
+      const request = async (path, init = {}) =>
+        bounded(signal, 30_000, async (requestSignal) => {
+          const response = await fetch(base + path, {
+            mode: 'cors',
+            credentials: 'omit',
+            cache: 'no-store',
+            redirect: 'error',
+            targetAddressSpace: 'loopback',
+            ...init,
+            signal: AbortSignal.any([requestSignal, init.signal].filter(Boolean))
           })
-          if (value?.code !== 'cancelled' || value.proof !== (await sign('cancelled')))
-            throw new BrowserImportError(
-              'incompatible',
-              'Could not verify the local receiver identity.'
+          const value = await response.json().catch((error) => {
+            if (response.status === 410) {
+              throw new BrowserImportError(
+                'incompatible',
+                'Could not verify the local receiver identity.'
+              )
+            }
+            throw error
+          })
+          if (response.status === 410) {
+            if (value?.code !== 'cancelled' || value.proof !== (await sign('cancelled')))
+              throw new BrowserImportError(
+                'incompatible',
+                'Could not verify the local receiver identity.'
+              )
+            cancelled = new BrowserImportError(
+              'cancelled',
+              'The transfer was cancelled in Open-Science. Prepare a new transfer to try again.'
             )
-          cancelled = new BrowserImportError(
-            'cancelled',
-            'The transfer was cancelled in Open-Science. Prepare a new transfer to try again.'
-          )
-          throw cancelled
-        }
-        return response
-      }
+            throw cancelled
+          }
+          return { ok: response.ok, status: response.status, value }
+        })
       try {
         onPhase?.('waiting-for-receiver')
-        // Browser protocol prompts have no observable completion event. Only this secret's proof
-        // ends launch waiting; the bounded deadline covers requests, body reads and retry gaps.
-        const budget = Math.min(readyTimeoutMs, waitingForLaunch ? 120_000 : 300_000)
+        // Count-only polling survives page suspension without consuming an overall deadline.
+        // Numeric/default budgets retain the legacy deadline across requests, bodies and gaps.
+        const budget = countOnly
+          ? null
+          : Math.min(readyTimeoutMs, waitingForLaunch ? 120_000 : 300_000)
         const attemptBudget = waitingForLaunch ? Math.min(attemptTimeoutMs, 2000) : attemptTimeoutMs
-        const deadline = Date.now() + budget
-        const ready = await bounded(signal, budget, async (readySignal) => {
+        const deadline = budget === null ? null : Date.now() + budget
+        const poll = async (readySignal) => {
           for (let attempt = 0; waitingForLaunch || attempt < readinessAttempts; attempt++) {
             readySignal.throwIfAborted()
             try {
@@ -259,7 +293,7 @@ export function prepareBrowserImport(file, options = {}) {
                 const response = await request(`/ready?challenge=${challenge}`, {
                   signal: attemptSignal
                 })
-                const value = await response.json()
+                const value = response.value
                 if (
                   !value ||
                   typeof value !== 'object' ||
@@ -277,7 +311,7 @@ export function prepareBrowserImport(file, options = {}) {
                   `open-science-import-v1:${challenge}:${value.offset}:${value.accepted ? 1 : 0}`
                 )
                 attemptSignal.throwIfAborted()
-                if (Date.now() >= deadline)
+                if (deadline !== null && Date.now() >= deadline)
                   throw new BrowserImportError(
                     'timeout',
                     'Open-Science did not become ready in time.'
@@ -297,14 +331,16 @@ export function prepareBrowserImport(file, options = {}) {
                   'incompatible',
                   'Could not verify the local receiver identity.'
                 )
-              if (waitingForLaunch || attempt + 1 < readinessAttempts) await wait(1000, readySignal)
+              if (waitingForLaunch || attempt + 1 < readinessAttempts)
+                await wait(readinessIntervalMs, readySignal)
             }
           }
           throw new BrowserImportError(
             'readiness-exhausted',
             'Open-Science did not become ready. Open the app, allow local network access, and retry.'
           )
-        })
+        }
+        const ready = budget === null ? await poll(signal) : await bounded(signal, budget, poll)
         verified = true
         if (
           !Number.isSafeInteger(ready.offset) ||
@@ -338,7 +374,7 @@ export function prepareBrowserImport(file, options = {}) {
               }
             })
             if (!chunk.ok) throw new Error(`Local package transfer failed (${chunk.status}).`)
-            const result = await chunk.json()
+            const result = chunk.value
             if (
               result.offset !== offset + bytes.byteLength ||
               result.proof !== (await sign(`offset:${result.offset}`))
@@ -351,7 +387,7 @@ export function prepareBrowserImport(file, options = {}) {
             method: 'POST',
             headers: await authorize('POST', '/complete')
           })
-          const receipt = await complete.json()
+          const receipt = complete.value
           if (
             complete.status !== 202 ||
             receipt.received !== true ||
@@ -362,17 +398,7 @@ export function prepareBrowserImport(file, options = {}) {
         received = true
         return { received: true }
       } catch (error) {
-        if (verified && signal?.aborted) {
-          await fetch(base, {
-            method: 'DELETE',
-            mode: 'cors',
-            credentials: 'omit',
-            redirect: 'error',
-            headers: await authorize('DELETE', ''),
-            signal: AbortSignal.timeout(2000),
-            targetAddressSpace: 'loopback'
-          }).catch(() => undefined)
-        }
+        if (signal?.aborted) await cancel()
         signal?.throwIfAborted()
         if (error.code === 'cancelled' || error.code === 'incompatible') throw error
         if (verified)

package/cli.mjs

@@ -5,14 +5,19 @@
 import { randomUUID } from 'node:crypto'
 import { closeSync, createWriteStream, existsSync, openSync, realpathSync } from 'node:fs'
 import { chmod, lstat, mkdir, readFile, readlink, rename, rm, stat } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { text as readStreamText } from 'node:stream/consumers'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
-import { findServiceState, readWebToken, resolveConfigRoot } from './config-root.mjs'
+import {
+  candidateConfigRoots,
+  findServiceState,
+  readWebToken,
+  resolveConfigRoot
+} from './config-root.mjs'
 import { codexLoginCommand } from './codex-login.mjs'
 import { connectToOpenScience, OpenScienceApiError } from './index.mjs'
 import { locateBackend } from './locate-backend.mjs'
@@ -27,6 +32,9 @@ const MAX_DOWNLOAD_SYMLINK_HOPS = 40
 const usage = `Usage: open-science <command> [options]
 
 Commands:
+  version     Print the local application version (also --version or -v)
+  help [command]  Show general or command help
+  paths       Show local CLI, Node and configuration discovery paths
   init        Create the local CLI configuration directory
   start       Start the headless backend and localhost web UI
   stop        Gracefully stop the backend
@@ -54,6 +62,8 @@ Commands:
   session status <session-id>
   session config show <session-id>
   session config update <session-id> --revision <number> [session options]
+  session export <session-id> --project <id-or-name> --output <path>
+  session import <path> [--project <id-or-name> | --new-project <name>] --non-interactive
   settings agent-routing show
   settings agent-routing update [routing options]
   plan show <session-id>
@@ -101,14 +111,17 @@ Options:
   --wait                 Wait for the run to finish
   --return-on-attention  With --wait, return when the Plan needs approval
   --timeout-ms <ms>      Stop waiting after this many milliseconds
+  --output <path>        Destination path (session export, artifacts download)
+  --new-project <name>   Import into a new Project with this name (session import)
+  --non-interactive      Import without an interactive preview confirmation (session import)
   --cancel-on-timeout    Cancel the server run when --timeout-ms expires
   --jsonl                With run --wait, stream one machine-readable event per line
-  --output <path>        Artifact download destination
   --credential-store <os|file>  Settings credential storage (Linux headless; start only)
   --no-open              Do not open the browser after start
   --no-sandbox           Disable Chromium's process sandbox (security risk; start only)
   --force                Sign in again even when Codex credentials already exist
   --json                 Emit one machine-readable result
+  -v, --version          Print the local application version and exit
   -h, --help             Show this help`
 
 // Flags that take a value, mapped to their camelCase option key (explicit so new hyphenated flags
@@ -151,7 +164,8 @@ const VALUE_OPTIONS = {
   '--description': 'description',
   '--agent-context': 'agentContext',
   '--agent-context-file': 'agentContextFile',
-  '--output': 'output'
+  '--output': 'output',
+  '--new-project': 'newProject'
 }
 
 const TASK_COMMANDS = new Set([
@@ -186,6 +200,9 @@ const GROUP_COMMANDS = new Set([
 // Project create, update, and session-defaults intentionally remain unbounded because their
 // positional Project names may contain multiple unquoted words.
 const POSITIONAL_LIMITS = new Map([
+  ['version', 0],
+  ['help', 1],
+  ['paths', 0],
   ['doctor', 0],
   ['runtime list', 0],
   ['runtime install', 1],
@@ -216,6 +233,8 @@ const POSITIONAL_LIMITS = new Map([
   ['run cancel', 1],
   ['session status', 1],
   ['session config', 2],
+  ['session export', 1],
+  ['session import', 1],
   ['settings agent-routing', 1],
   ['plan show', 1],
   ['plan approve', 1],
@@ -255,7 +274,17 @@ const assertPositionalLimit = (command, subcommand, positionals) => {
 
 export const parseCliArgs = (argv) => {
   const args = [...argv]
-  const command = args.shift()
+  const requestedCommand = args.shift()
+  const command =
+    requestedCommand === '--version' || requestedCommand === '-v' ? 'version' : requestedCommand
+  const localOptions =
+    command === 'version'
+      ? ['--json', '--help', '-h']
+      : command === 'paths'
+        ? ['--json', '--help', '-h', '--config-root', '--profile']
+        : command === 'help'
+          ? ['--help', '-h']
+          : undefined
   const subcommand =
     (GROUP_COMMANDS.has(command) && args[0] && !args[0].startsWith('-')) ||
     (command === 'run' && (args[0] === 'status' || args[0] === 'cancel'))
@@ -270,6 +299,9 @@ export const parseCliArgs = (argv) => {
   const positionals = []
   while (args.length > 0) {
     const arg = args.shift()
+    if (localOptions && arg.startsWith('-') && !localOptions.includes(arg)) {
+      throw new CliUsageError(`Unknown option for ${command}: ${arg}`)
+    }
     if (arg.startsWith('--credential-store=')) {
       if (options.credentialStore !== undefined)
         throw new CliUsageError('Specify --credential-store only once.')
@@ -284,6 +316,7 @@ export const parseCliArgs = (argv) => {
     else if (arg === '--wait') options.wait = true
     else if (arg === '--return-on-attention') options.returnOnAttention = true
     else if (arg === '--plan-first') options.planFirst = true
+    else if (arg === '--non-interactive') options.nonInteractive = true
     else if (arg === '--provider-default-model') options.providerDefaultModel = true
     else if (arg === '--clear-compute-hosts') options.clearComputeHosts = true
     else if (arg === '--memory') {
@@ -347,6 +380,10 @@ export const parseCliArgs = (argv) => {
     ...(positionals.length ? { positionals } : {}),
     options
   }
+  if (localOptions) {
+    assertPositionalLimit(command, subcommand, positionals)
+    return parsed
+  }
   // Help is local: it must not require execution-only options or a running backend.
   if (options.help) return parsed
   if (options.port !== undefined) {
@@ -435,8 +472,18 @@ export const parseCliArgs = (argv) => {
   if (options.jsonl && (command !== 'run' || subcommand || !options.wait)) {
     throw new CliUsageError('--jsonl requires run --wait.')
   }
-  if (options.timeoutMs !== undefined && (command !== 'run' || subcommand || !options.wait)) {
-    throw new CliUsageError('--timeout-ms requires run --wait.')
+  const isPackageTransfer = command === 'session' && ['export', 'import'].includes(subcommand)
+  if (
+    options.timeoutMs !== undefined &&
+    !isPackageTransfer &&
+    (command !== 'run' || subcommand || !options.wait)
+  ) {
+    throw new CliUsageError('--timeout-ms requires run --wait or session export/import.')
+  }
+  if (command === 'session' && subcommand === 'import') {
+    if (!options.nonInteractive) throw new CliUsageError('--non-interactive is required.')
+    if (options.project && options.newProject)
+      throw new CliUsageError('Use only one of --project and --new-project.')
   }
   if (options.returnOnAttention && (command !== 'run' || subcommand || !options.wait)) {
     throw new CliUsageError('--return-on-attention requires run --wait.')
@@ -1514,6 +1561,40 @@ export const runTaskCommand = async (parsed, dependencies = {}) => {
     )
     return
   }
+  if (command === 'session' && subcommand === 'export') {
+    const sessionId = positionals[0]
+    if (!sessionId) throw new CliUsageError('Session id is required.')
+    if (!options.project) throw new CliUsageError('--project is required.')
+    if (!options.output) throw new CliUsageError('--output is required.')
+    const projectId = await resolveCliProjectId(client, options.project)
+    outputValue(
+      await client.exportSessionPackage(projectId, sessionId, resolve(options.output), {
+        timeoutMs: options.timeoutMs
+      }),
+      options,
+      deps
+    )
+    return
+  }
+  if (command === 'session' && subcommand === 'import') {
+    const packagePath = positionals[0]
+    if (!packagePath) throw new CliUsageError('Session package path is required.')
+    const resolvedPath = resolve(packagePath)
+    const target = {}
+    if (options.project) target.projectId = await resolveCliProjectId(client, options.project)
+    else if (options.newProject) target.projectName = options.newProject
+    outputValue(
+      await client.importSessionPackage(
+        target,
+        resolvedPath,
+        { nonInteractive: true },
+        { timeoutMs: options.timeoutMs }
+      ),
+      options,
+      deps
+    )
+    return
+  }
   if (command === 'settings' && subcommand === 'agent-routing') {
     const action = positionals[0]
     if (action === 'show') {
@@ -1749,14 +1830,55 @@ ${commands.join('\n')}
 Run "open-science --help" for the complete option reference.`
 }
 
+const readCliMetadata = async () => {
+  const here = dirname(fileURLToPath(import.meta.url))
+  // Source SDK metadata has its own version; installed CLI manifests carry the release version.
+  const development =
+    basename(here) === 'open-science' &&
+    basename(dirname(here)) === 'packages' &&
+    existsSync(join(here, '../../src/main/node-entry.ts'))
+  const manifestPath = join(development ? join(here, '../..') : here, 'package.json')
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  if (
+    manifest.name !== (development ? 'open-science' : '@aipoch/open-science') ||
+    typeof manifest.version !== 'string' ||
+    !/^\d+\.\d+\.\d+(?:-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/.test(manifest.version)
+  ) {
+    throw new Error(`Invalid Open-Science CLI metadata: ${manifestPath}`)
+  }
+  return { version: manifest.version, development }
+}
+
+const pathsCommand = async (options) => {
+  const { development } = await readCliMetadata()
+  const paths = {
+    cliPath: fileURLToPath(import.meta.url),
+    nodePath: process.execPath,
+    startupConfigRoot: resolveConfigRoot({
+      packaged: !development,
+      override: options.configRoot
+    }),
+    discoveryConfigRoots: candidateConfigRoots({ override: options.configRoot })
+  }
+  console.log(
+    options.json
+      ? JSON.stringify(paths)
+      : `CLI: ${paths.cliPath}\nNode: ${paths.nodePath}\nStartup configuration: ${paths.startupConfigRoot}\nService discovery (in order):\n${paths.discoveryConfigRoots.map((root) => `  ${root}`).join('\n')}`
+  )
+}
+
 export const runCli = async (argv = process.argv.slice(2)) => {
   const parsed = parseCliArgs(argv)
   const { command, options } = parsed
-  if (options.help || !command || command === '-h' || command === '--help') {
-    console.log(commandHelp(command))
+  if (options.help || !command || command === 'help' || command === '-h' || command === '--help') {
+    console.log(commandHelp(command === 'help' ? parsed.positionals?.[0] : command))
     return
   }
-  if (command === 'init') await initCommand(options)
+  if (command === 'version') {
+    const { version } = await readCliMetadata()
+    console.log(options.json ? JSON.stringify({ version }) : version)
+  } else if (command === 'paths') await pathsCommand(options)
+  else if (command === 'init') await initCommand(options)
   else if (command === 'start') await startCommand(options)
   else if (command === 'stop') await stopCommand(options)
   else if (command === 'status') await statusCommand(options)

package/index.d.ts

@@ -99,6 +99,7 @@ export type ConnectorsSnapshot = {
   ncbi: NcbiCredentialsView
   // Optional only for compatibility with an older main process during local development.
   openAlex?: OpenAlexCredentialView
+  semanticScholar?: { hasApiKey: boolean }
 }
 
 export type DeviceCredentialKind = 'api_key' | 'token' | 'oauth'

package/index.mjs

@@ -6,6 +6,7 @@ const defaultSleep = (milliseconds) =>
   new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds))
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+const PACKAGE_REQUEST_TIMEOUT_MS = 60 * 60 * 1_000
 const DEFAULT_EVENT_IDLE_TIMEOUT_MS = 30_000
 const EVENT_RECONNECT_DELAY_MS = 100
 const MAX_BUFFERED_EVENTS = 1_024
@@ -308,6 +309,54 @@ export class OpenScienceClient {
     return this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/config`, options)
   }
 
+  // Web RPC seam: authenticated loopback dispatch of one application command channel.
+  // The CLI reaches headless-only commands (Session package export/import) this way.
+  async callRpc(channel, args, options = {}) {
+    return withRequestTimeout(
+      {
+        defaultTimeoutMs: this.requestTimeoutMs,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+      },
+      async (signal) => {
+        const response = await this.fetch(`${this.baseUrl}/rpc/${encodeURIComponent(channel)}`, {
+          method: 'POST',
+          headers: {
+            authorization: `Bearer ${this.token}`,
+            accept: 'application/json',
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify({ protocolVersion: 1, args }),
+          signal
+        })
+        const payload = await response.json().catch(() => undefined)
+        if (!response.ok || payload?.ok !== true) {
+          throw new OpenScienceApiError(
+            payload?.error?.message ?? `Open-Science Web RPC request failed (${response.status}).`,
+            { code: payload?.error?.code, status: response.status }
+          )
+        }
+        return payload.result
+      }
+    )
+  }
+
+  exportSessionPackage(projectId, sessionId, destinationPath, options) {
+    return this.callRpc('sessions:export-package', [{ projectId, sessionId }, destinationPath], {
+      ...options,
+      timeoutMs: options?.timeoutMs ?? PACKAGE_REQUEST_TIMEOUT_MS
+    })
+  }
+
+  importSessionPackage(target, sourcePath, options, rpcOptions) {
+    if (options?.nonInteractive !== true)
+      throw new TypeError('Non-interactive Session import requires explicit confirmation.')
+    return this.callRpc('sessions:import-package', [target, sourcePath, { nonInteractive: true }], {
+      ...rpcOptions,
+      timeoutMs: rpcOptions?.timeoutMs ?? PACKAGE_REQUEST_TIMEOUT_MS
+    })
+  }
+
   updateSessionConfiguration(sessionId, request, options) {
     return this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/config`, {
       ...options,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipoch/open-science",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Node.js SDK and CLI for the Open-Science local daemon",
   "type": "module",
   "exports": {
@@ -38,10 +38,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@aipoch/open-science-darwin-arm64": "1.0.1",
-    "@aipoch/open-science-darwin-x64": "1.0.1",
-    "@aipoch/open-science-linux-x64-gnu": "1.0.1",
-    "@aipoch/open-science-linux-arm64-gnu": "1.0.1",
-    "@aipoch/open-science-win32-x64": "1.0.1"
+    "@aipoch/open-science-darwin-arm64": "1.0.3",
+    "@aipoch/open-science-darwin-x64": "1.0.3",
+    "@aipoch/open-science-linux-x64-gnu": "1.0.3",
+    "@aipoch/open-science-linux-arm64-gnu": "1.0.3",
+    "@aipoch/open-science-win32-x64": "1.0.3"
   }
 }