ScienceDiscovery
中文 GitHub

Runtime Behavior Reference

The root README covers basic use. This page documents models, setting inheritance, skills, permissions and review, timeouts, session lifecycle, execution limits, and paper-reader limits.

Models

Each model configuration has a display name, base URL such as https://api.openai.com/v1, model ID, optional Vision capable flag, and external model API Key.

Runtime settings and inheritance

Task model, evidence-review model, enabled connectors, and semantic-review setting are each resolved independently: Global defaults, then Project override, then Session override. An Inherit field follows later parent changes and the editor displays the effective value and source. Connector lists replace the whole parent list; an explicit empty list disables all inherited connectors.

Skill selection starts at Project scope. Its default all mode exposes every installed skill to runs and /; Global has no skill setting. Project can select a whitelist and Session can inherit or override it. In selected mode, / suggests only effective skills and runs reject attachments outside the whitelist.

New Sessions inherit by default, but creation still requires a resolved task model with a saved provider token. A run snapshots settings at startup; later parent changes do not rewrite running or historical configuration.

Skill management

System configuration → Skills contains built-in skills and local packages. Portable packages use:

my-skill/
  SKILL.md          # required YAML frontmatter and Markdown instructions
  scripts/          # optional; retained, never auto-executed or auto-copied
  references/       # optional text resources
  assets/           # optional package resources

SKILL.md requires a lowercase kebab-case name matching the directory and a non-empty description. The manager supports editing, natural-language drafts, reviewable Session distillation, local folder/Markdown/ZIP import, and Git import from HTTPS/SSH URL with optional ref/subdirectory. A user may also explicitly request Skill creation in chat: the main Agent must progressively load the built-in skill-creator before create_skill writes an inactive review draft; subagents do not receive this tool. Repeated changes to the same pending Skill update one review item and retain proposal history for comparison. Pending drafts appear in Settings > Skills without opening a dialog automatically, and completed create_skill calls expose a conversation shortcut to that page. The Skills Explorer lists every package and file, exposes installed revisions and Agent proposals on one timeline, and lets the user choose any versions A and B for a line-aligned diff. Any UTF-8 file in a managed Skill can be edited; saving creates the next immutable revision, while built-in Skills remain read-only. Only explicit confirmation installs a pending revision; discarding a draft leaves the active catalog unchanged. Folder import preserves relative paths and packages the selection in the browser before reusing the ZIP validation path. Git credentials stay in the local credential helper or SSH configuration and are not placed in URLs or model context. Registries, marketplaces, signatures, and automatic updates are unsupported.

There is one global skill library. New/imported skills are immediately available in all mode; narrow them at Project or Session scope. Each managed edit creates an immutable revision, runs freeze selected revisions, and Prompt Manifest records IDs, revisions, versions, and package hashes. Only selected-mode references prevent deletion.

The staged-path Skill loading described below applies to the native executor. The default JiuwenSwarm backend installs selected Skills for skill_tool; read_skill and read_skill_resource remain fallback paths if that loading fails. See Agent backends.

Imports are untrusted. ZIP validation rejects traversal, symlinks, encryption, duplicates, and excess limits: 25 MiB upload, 50 MiB expanded, 500 files, 10 MiB per resource, and 512 KiB SKILL.md. Prompts list name, description, revision, package path, and package hash rather than package content. Before the sandbox starts, the complete frozen package of every selected Skill is staged read-only at $SCIENCEDISCOVERY_SKILLS_DIR/<skillId>, so the model reads SKILL.md, supporting text, and bundled files as ordinary paths and executes a bundled script in place with explicit argv. Always address a package through that variable: it expands to the bind path /skills under bubblewrap and to the real host directory under macOS Seatbelt, so a hardcoded /skills is Linux-only. One selected Skill set is staged once per Session as a content-addressed directory, so runs that select the same frozen revisions share it. read_skill and bounded read_skill_resource remain available as compatibility channels. Staging is not installing: selecting a Skill never auto-runs scripts/ or installs dependencies, and the default package tree rejects writes and deletes. $SCIENCEDISCOVERY_SKILL_EXTENSIONS_DIR is a writable area reserved for later self-evolution and starts empty. The model should neither search the filesystem for package resources — the prompt already carries the path — nor read a large bundled script back into context.

Managed scientific environments

Runner startup and health do not wait for environment installation. A new data directory downloads and verifies application-owned micromamba in the background and creates only the Python base. System configuration → Environments shows state, phase, description, failure, and timestamps and permits retry. R is downloaded only on the first explicit named-R environment creation; existing R bases survive upgrades.

Each Runner owns an environment catalog shared by its Projects. Python/R bases are read-only and undeletable. A named environment may contain both languages. Controlled package updates change its prefix in place and advance currentRevisionId, an audit record rather than a runnable historical copy. Executions select an environment ID and resolve its latest state. Managed prefixes are read-only inside the sandbox; prompts direct package changes to environment tools without intercepting Shell commands. See execution and Workspace lifecycle.

Permissions and reviewer

Enabling a connector or runtime does not authorize its execution. The first matching code or connector action pauses for a permission card unless a non-revoked grant exists. Persistent grants are managed under System configuration → Permissions. Directory tools remain inside the workspace; permission never disables Bubblewrap isolation and never changes the effective sandbox network policy, which only the system setting decides.

Reviewer Specialist is off by default. Once enabled, Run review or an explicit request reviews an Artifact. Quick review checks citation format and computation provenance, persists a separate card, and supplies it to later main-agent context without blocking the current conversation. Text versions expose a diff while both immutable versions remain stored.

Timeouts and run status

System configuration → Timeouts controls agent idle, full agent turn, runner execution, persistent-kernel idle, and permission-wait wall-clock limits. Agent idle stops a turn with no stream output or progress; agent turn bounds model, tools, and streaming together. Every field supports Unlimited (0 in API/environment variables). The default idle timeout is 240 seconds and the other four are unlimited. Environment variables seed a new data directory; persisted UI values then take precedence. Internal request-signature freshness windows are deliberately not exposed.

System configuration → Runtime status auto-refreshes active Session runs, runner queue/running tasks, and persistent kernels. A timeout reports its reason and duration in the stream and Session history. Stop run cancels the run through gateway and callbacks, kills in-flight Bubblewrap execution, and removes queued runner work. Runtime status can Teardown a kernel by ID. Downstream HTTP guards for reviewer, paper worker, and connector IO are separate from these product settings.

Session lifecycle and deletion

Use Active, Archived, or All filters. Archiving preserves messages, files, papers, and audit history but makes a Session read-only until restored: runs, settings, uploads, connector calls, paper changes, and permission changes are rejected.

Delete is irreversible. The UI requests a server-side impact preview and requires the exact resource name. Session deletion removes its workspace and history; Project deletion cascades to all active and archived Sessions and Project settings. Back up the data directory first if it might be needed.

Execution limits

There are no compute tiers or CPU/memory quotas. Guardrails are a configurable execution wall clock (unlimited locally by default), 10 GiB runner workspace, 1 GiB retained stdout+stderr per execution with truncation, and one global execution worker. There is no separate runner per-file limit. API upload limits are instead 1 GiB per file, 10 GiB per request, and 10 GiB cumulative workspace. See Quota levels. Isolation remains Bubblewrap namespaces, seccomp, and only the Session workspace visible from the host filesystem. Network is a policy, not a constant: it defaults to none (no interface in the sandbox), and when an administrator enables a domain allowlist under System configuration → Sandbox network the sandbox still has no interface — outbound traffic leaves only through this deployment's egress gateway, filtered by the allowed domains. The effective policy is snapshotted into the Permission Epoch and reported at /api/health.sandboxNetwork; see Sandbox execution.

Paper reader limits

PDFs are limited to 50 MiB and 200 pages; extraction caps are 20 million text characters, 256 tables, 128 figures, and 24 page previews. There is no OCR. Pages with little embedded text may be marked for a vision-capable model, which analyzes at most four images. Vision output is model interpretation, not authoritative transcription.

Article-level license constraints are reused. The Europe PMC open-access PDF path still uses the legacy PMC OA Web Service/HTTPS layout scheduled for retirement in August 2026.