@aipoch/open-science 1.0.2 → 1.0.3

package/CLI.md

@@ -606,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/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

@@ -62,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>
@@ -109,9 +111,11 @@ 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)
@@ -160,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([
@@ -228,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],
@@ -309,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') {
@@ -464,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.')
@@ -1543,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') {

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.2",
+  "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.2",
-    "@aipoch/open-science-darwin-x64": "1.0.2",
-    "@aipoch/open-science-linux-x64-gnu": "1.0.2",
-    "@aipoch/open-science-linux-arm64-gnu": "1.0.2",
-    "@aipoch/open-science-win32-x64": "1.0.2"
+    "@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"
   }
 }