@aipoch/open-science 1.0.2 → 1.0.4

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:
@@ -812,3 +849,83 @@ older releases. To switch a file credential back to OS storage, restart in OS mo
 replace it with the key while the vault is available. Existing unreadable records remain intact.
 These commands do not migrate historical configuration or store diagnostic history. Older backends that
 lack the endpoints return an endpoint error; the CLI never falls back to editing Settings files directly.
+
+## External agents through MCP
+
+Start the selected profile normally, then let an MCP client launch the stdio adapter:
+
+```bash
+open-science start --no-open --config-root /absolute/path/to/profile
+open-science mcp --config-root /absolute/path/to/profile
+```
+
+Example client configuration (replace paths with your installation and profile paths):
+
+```json
+{
+  "mcpServers": {
+    "open-science": {
+      "command": "/absolute/path/to/open-science",
+      "args": ["mcp", "--config-root", "/absolute/path/to/profile"]
+    }
+  }
+}
+```
+
+`--profile` is an alias for `--config-root`; existing environment overrides and discovery order
+apply. For a source checkout, use `node` as the command and put the absolute path to
+`packages/open-science/cli.mjs` before `mcp` in `args`. The adapter connects to an already
+running authenticated local service; it does not start it, install anything or open a browser.
+`open-science mcp --help` works without a running service.
+
+Tool discovery works even when the service is stopped. Calls return an actionable error until
+it is available, and subsequent calls rediscover the service. Tool names consistently use
+lowercase `snake_case`; argument names retain the SDK's `camelCase`. Tools accept explicit IDs
+rather than resolving project names. Each tool publishes its description, input schema, output
+schema and behavior annotations through `tools/list`.
+
+| Tool                           | Purpose                                                  |
+| ------------------------------ | -------------------------------------------------------- |
+| `doctor`                       | Check research readiness                                 |
+| `list_runtimes`                | List detected Agent runtimes                             |
+| `list_projects`                | List projects and IDs                                    |
+| `create_project`               | Create a persistent project                              |
+| `update_project`               | Update project metadata and Agent Context                |
+| `list_sessions`                | List sessions, optionally by project                     |
+| `get_session`                  | Read session information/status, not a full transcript   |
+| `get_session_configuration`    | Read session configuration and revision                  |
+| `update_session_configuration` | Update settings with `expectedRevision`                  |
+| `start_run`                    | Submit a prompt and return a run ID                      |
+| `get_run`                      | Read progress, output and attention state                |
+| `cancel_run`                   | Explicitly cancel a run without undoing previous effects |
+| `get_plan`                     | Read the plan and its version/revision                   |
+| `respond_plan`                 | Approve/reject a reviewed version or request changes     |
+| `list_artifacts`               | List artifact metadata without downloading files         |
+
+A typical workflow calls `list_projects`, `start_run` with `{ "projectId": "…", "prompt": "…" }`,
+then polls `get_run` with the returned run ID and calls `list_artifacts` with the session ID.
+Successful calls return `structuredContent: { "result": ... }` plus the same JSON in text
+content. Tool execution failures set `isError: true`; exception bodies and credentials are not
+forwarded. After a timeout or transport failure, inspect current state before repeating a write:
+the original operation may already have succeeded. The adapter never retries mutations itself.
+
+Runs use the service's configured framework and authorization defaults. `start_run` accepts
+existing session, provider/model, permission, skill, specialist, compute-host, memory, review,
+delegation and plan-first options; it does not change the global framework. A run can require
+human action in Open-Science. Explicit `permissionPrompts: "none"` denies unresolved human
+interactions using the existing capability check; it does not expand permissions and cannot
+be combined with `turnIntent: "plan-first"`. Plan approval/rejection requires the version and
+revision from `get_plan`. Configuration updates require the revision from
+`get_session_configuration`.
+
+MCP access grants the listed operations for the selected profile under its existing permissions.
+The adapter is not a separate sandbox or a read-only view. Project/configuration changes, plan
+responses and research runs persist through existing business owners and may write files or
+incur model costs. No new database schema, historical-data migration, business status enum,
+credential store or background service is introduced. There is no arbitrary shell/RPC tool,
+credential-management tool, file import/export/download-to-path tool or remote HTTP MCP endpoint.
+
+Standard output carries only MCP protocol messages. Closing stdin or sending SIGINT/SIGTERM
+closes the adapter and its pending network requests; it neither stops the service nor cancels
+accepted runs. MCP request cancellation likewise stops waiting, not the persisted operation.
+Use `cancel_run` explicitly to cancel research.

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

@@ -40,6 +40,7 @@ Commands:
   stop        Gracefully stop the backend
   status      Show backend status
   url         Print the authenticated web URL
+  mcp         Serve research tools over MCP stdio (--config-root <path> or --profile <path>)
   doctor --json  Inspect headless readiness
   runtime list          List detected Agent runtimes
   runtime install codex   Prepare the app-managed Codex runtime
@@ -62,6 +63,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 +112,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 +165,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([
@@ -198,6 +204,7 @@ const POSITIONAL_LIMITS = new Map([
   ['version', 0],
   ['help', 1],
   ['paths', 0],
+  ['mcp', 0],
   ['doctor', 0],
   ['runtime list', 0],
   ['runtime install', 1],
@@ -228,6 +235,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],
@@ -275,9 +284,11 @@ export const parseCliArgs = (argv) => {
       ? ['--json', '--help', '-h']
       : command === 'paths'
         ? ['--json', '--help', '-h', '--config-root', '--profile']
-        : command === 'help'
-          ? ['--help', '-h']
-          : undefined
+        : command === 'mcp'
+          ? ['--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'))
@@ -309,6 +320,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 +476,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 +1565,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') {
@@ -1826,7 +1882,11 @@ export const runCli = async (argv = process.argv.slice(2)) => {
     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 === 'mcp') {
+    const { runResearchMcpServer } = await import('./mcp.mjs')
+    const { version } = await readCliMetadata()
+    await runResearchMcpServer({ configRoot: options.configRoot, version })
+  } 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/mcp.mjs

@@ -0,0 +1,310 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { connectToOpenScience, OpenScienceApiError } from './index.mjs'
+
+const id = (description) => z.string().trim().min(1).describe(description)
+const sessionId = id('Session ID returned by list_sessions or start_run.')
+const projectId = id('Project ID returned by list_projects or create_project.')
+const runId = id('Run ID returned by start_run.')
+const expectedRevision = z
+  .number()
+  .int()
+  .nonnegative()
+  .describe(
+    'Current revision returned by the corresponding read tool. Stale revisions are rejected.'
+  )
+const agentConfiguration = z.strictObject({
+  providerId: id('Configured provider ID.').optional(),
+  model: id('Model identifier; null follows the provider default.').nullable().optional(),
+  reasoningEffort: z.enum(['default', 'low', 'medium', 'high', 'xhigh', 'max']).optional()
+})
+const sessionSettings = {
+  agentConfiguration: agentConfiguration.optional(),
+  permissionProfile: z
+    .enum(['ask', 'auto', 'full'])
+    .describe(
+      'Existing authorization policy. Omit to retain configured defaults; full grants broad execution authority.'
+    )
+    .optional(),
+  autoReviewEnabled: z.boolean().optional(),
+  memoryEnabled: z.boolean().optional(),
+  delegationPolicy: z.enum(['allow', 'deny']).optional()
+}
+const agentContext = z.string().trim().min(1).max(16000)
+const read = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+}
+const write = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
+}
+const result = (value) => ({
+  content: [{ type: 'text', text: JSON.stringify({ result: value ?? null }) }],
+  structuredContent: { result: value ?? null }
+})
+
+// Do not forward raw exception messages: HTTP failures may contain credentials or response bodies.
+const toolError = (error) => {
+  const messages = {
+    daemon_unavailable:
+      'Open-Science is not running. Start it with "open-science start" for the selected profile, then retry.',
+    unsupported_capability:
+      'The service does not support this operation. Update the service before retrying.',
+    project_not_found: 'Project not found. Refresh list_projects.',
+    session_not_found: 'Session not found. Refresh list_sessions.',
+    run_not_found: 'Run not found. Check the ID returned by start_run.',
+    invalid_request: 'Invalid request. Check the tool arguments and service configuration.',
+    request_timeout:
+      'Request timed out. A write may already have succeeded; check its state before retrying.'
+  }
+  const code =
+    error instanceof OpenScienceApiError && Object.hasOwn(messages, error.code)
+      ? error.code
+      : 'request_failed'
+  const status = error instanceof OpenScienceApiError ? error.status : undefined
+  const message =
+    status === 401 || status === 403
+      ? 'Access denied. Check the selected profile and its service credentials.'
+      : status === 409
+        ? 'The operation conflicts with current state. Read the latest state and revision before retrying.'
+        : (messages[code] ??
+          'The operation failed. Check service readiness and request arguments. A write may already have succeeded; inspect its state before retrying.')
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify({ error: { code, message } }) }]
+  }
+}
+
+export const createResearchMcpServer = ({
+  configRoot,
+  version,
+  connect = connectToOpenScience
+}) => {
+  const server = new McpServer({ name: 'open-science', version })
+  const lifetime = new AbortController()
+  const register = (name, description, shape, annotations, invoke) => {
+    server.registerTool(
+      name,
+      {
+        description,
+        inputSchema: z.strictObject(shape),
+        outputSchema: z.object({ result: z.unknown() }),
+        annotations
+      },
+      async (args, extra) => {
+        const signal = AbortSignal.any([lifetime.signal, extra.signal])
+        try {
+          signal.throwIfAborted()
+          // Rediscover per call so service restarts/token rotation recover without retrying writes.
+          const client = await connect({ configRoot, signal })
+          signal.throwIfAborted()
+          return result(await invoke(client, args, { signal }))
+        } catch (error) {
+          return toolError(error)
+        }
+      }
+    )
+  }
+  register(
+    'doctor',
+    'Check whether the running Open-Science service is ready to execute research tasks. Does not start or configure the service.',
+    {},
+    read,
+    (client, _args, options) => client.doctor(options)
+  )
+  register(
+    'list_runtimes',
+    'List detected Agent runtimes and readiness. Does not install runtimes or change the selected framework.',
+    {},
+    read,
+    (client, _args, options) => client.listRuntimes(options)
+  )
+  register(
+    'list_projects',
+    'List projects and their IDs before choosing a research destination.',
+    {},
+    read,
+    (client, _args, options) => client.listProjects(options)
+  )
+  register(
+    'create_project',
+    'Create a persistent research project. Agent Context applies to future work in this project.',
+    {
+      name: id('Project name.'),
+      description: z.string().optional(),
+      agentContext: agentContext.optional()
+    },
+    write,
+    (client, args, options) => client.createProject(args, options)
+  )
+  register(
+    'update_project',
+    'Update a persistent project. Only supplied fields change; null clears Agent Context.',
+    {
+      projectId,
+      name: id('New project name.').optional(),
+      description: z.string().optional(),
+      agentContext: agentContext.nullable().optional()
+    },
+    write,
+    (client, { projectId, ...patch }, options) => client.updateProject(projectId, patch, options)
+  )
+  register(
+    'list_sessions',
+    'List sessions, optionally within one project. Use the returned ID to inspect or continue a session.',
+    {
+      projectId: projectId.optional()
+    },
+    read,
+    (client, args, options) => client.listSessions(args.projectId, options)
+  )
+  register(
+    'get_session',
+    'Read session information and current status. This is not a full conversation transcript.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSession(args.sessionId, options)
+  )
+  register(
+    'get_session_configuration',
+    'Read current session configuration and revision before changing it.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSessionConfiguration(args.sessionId, options)
+  )
+  register(
+    'update_session_configuration',
+    'Update persistent session settings using the latest revision. May change model costs and execution permissions; only supplied fields change.',
+    {
+      sessionId,
+      expectedRevision,
+      ...sessionSettings,
+      computeHosts: z
+        .strictObject({
+          enabled: z.array(id('Enabled Compute Host ID.')),
+          selected: z.array(id('Selected Compute Host ID.'))
+        })
+        .optional()
+    },
+    write,
+    (client, { sessionId, ...patch }, options) =>
+      client.updateSessionConfiguration(sessionId, patch, options)
+  )
+  register(
+    'start_run',
+    'Submit research in a project and immediately return a run ID. Omit sessionId to create a session, or provide it to continue that session through its existing active branch. May write files/data and incur model charges. Poll get_run; disconnecting does not cancel the run. Uses configured framework and permissions, without automatically approving human interactions.',
+    {
+      projectId,
+      prompt: id('Research instructions.'),
+      sessionId: sessionId.optional(),
+      cwd: id('Working directory on the Open-Science host.').optional(),
+      ...sessionSettings,
+      skillIds: z.array(id('Skill ID.')).optional(),
+      specialist: id('Specialist ID or exact name for a new session.').optional(),
+      turnIntent: z
+        .literal('plan-first')
+        .describe('Require an approved plan before execution.')
+        .optional(),
+      permissionPrompts: z
+        .literal('none')
+        .describe(
+          'Deny unresolved human interactions instead of waiting; does not expand permissions. Incompatible with plan-first.'
+        )
+        .optional(),
+      computeHostIds: z.array(id('Selected Compute Host ID.')).optional(),
+      enabledComputeHostIds: z.array(id('Enabled Compute Host ID for a new session.')).optional()
+    },
+    write,
+    (client, { projectId, ...request }, options) => {
+      if (request.turnIntent === 'plan-first' && request.permissionPrompts === 'none') {
+        throw new OpenScienceApiError('Incompatible permission and planning options.', {
+          code: 'invalid_request'
+        })
+      }
+      return client.startRun({ project: projectId, ...request }, options)
+    }
+  )
+  register(
+    'get_run',
+    'Read authoritative run status, progress, result and attention state. Poll this after start_run; a waiting run may require human action in Open-Science.',
+    { runId },
+    read,
+    (client, args, options) => client.getRun(args.runId, options)
+  )
+  register(
+    'cancel_run',
+    'Explicitly cancel a research run and wait for service finalization. This does not undo files, data or costs already produced.',
+    { runId },
+    write,
+    (client, args, options) => client.cancelRun(args.runId, options)
+  )
+  register(
+    'get_plan',
+    'Read the current session plan, artifact version and revision, or null when there is no plan.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSessionPlan(args.sessionId, options)
+  )
+  register(
+    'respond_plan',
+    'Explicitly approve or reject the reviewed plan version, or request revision with feedback. Approval may resume execution and incur costs. Never approve without reviewing get_plan.',
+    {
+      sessionId,
+      response: z.union([
+        z.strictObject({
+          decision: z.enum(['approved', 'rejected']),
+          artifactVersionId: id('Plan artifact version returned by get_plan.'),
+          expectedRevision
+        }),
+        z.strictObject({ feedback: id('Requested changes to the plan.') })
+      ])
+    },
+    write,
+    (client, args, options) => client.respondSessionPlan(args.sessionId, args.response, options)
+  )
+  register(
+    'list_artifacts',
+    'List generated artifact metadata for a session. Does not download files or write local paths.',
+    { sessionId },
+    read,
+    (client, args, options) => client.listArtifacts(args.sessionId, options)
+  )
+
+  const onclose = server.server.onclose
+  server.server.onclose = () => {
+    lifetime.abort()
+    onclose?.()
+  }
+  return server
+}
+
+export const runResearchMcpServer = async (options) => {
+  const server = createResearchMcpServer(options)
+  const transport = new StdioServerTransport()
+  let closing
+  const close = () => {
+    closing ??= server.close().finally(() => {
+      process.stdin.off('end', close)
+      process.off('SIGINT', close)
+      process.off('SIGTERM', close)
+    })
+    return closing
+  }
+  process.stdin.once('end', close)
+  process.once('SIGINT', close)
+  process.once('SIGTERM', close)
+  try {
+    await server.connect(transport)
+    if (process.stdin.readableEnded) await close()
+  } catch (error) {
+    await close()
+    throw error
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipoch/open-science",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Node.js SDK and CLI for the Open-Science local daemon",
   "type": "module",
   "exports": {
@@ -37,11 +37,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^4.6.5"
+  },
   "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.4",
+    "@aipoch/open-science-darwin-x64": "1.0.4",
+    "@aipoch/open-science-linux-x64-gnu": "1.0.4",
+    "@aipoch/open-science-linux-arm64-gnu": "1.0.4",
+    "@aipoch/open-science-win32-x64": "1.0.4"
   }
 }