Create a research run

The default new-task page is a one-request composer: describe the outcome, attach any datasets, lattices, solver source, one solver folder, or other research files, and start. You do not need to select capabilities, metrics, or project plugins first. “Plugin” in this guide means a Scientific Agent project plugin.

Runtime still compiles and freezes a complete Research Contract. The connected Scientific Reasoner first returns a strict, non-authorizing intent draft; deterministic control code then chooses the attachment roles, capability leases, provider pins, acceptance gates, budget, and deliverables. autonomous-plan.json uses autonomous-task-plan-v2 and records both that planning provenance and a digest, so the short input does not make interpretation, execution authority, or stopping conditions invisible.

Default: start from one request

The composer asks for:

• a task description of up to 32,000 characters, including important numeric requirements and desired outputs;
• up to 20 optional attachments, currently no larger than 10 MiB for each file or encoded folder.

Runtime applies one generous execution ceiling automatically. The current autonomous contract reserves at least 2,000 solver calls and 250,000 training samples, alongside finite action, experiment, failure, model-call, token, and 12-hour wall-time fuses. These values are visible in Control Room's Budget tab. They limit runaway resource use but do not select or alter the research strategy.

A selected folder retains its directory_bundle identity and occupies one attachment slot. ZIP is used only as its deterministic internal transport encoding.

While the app remains open, the prompt, attachment objects, upload progress, and retry identity stay in a session-memory draft when you navigate to another page and return. A staged file is not uploaded again. Successful task creation clears the draft; restarting the app clears it as well, so raw File objects are never written to browser storage.

Planning before authority

After attachments are staged, Desktop performs the following in order:

1. Runtime builds bounded static attachment profiles and a normalized capability summary.
2. The connected Scientific Reasoner turns the request and those summaries into a schema-validated draft containing subtasks, data roles, capability requirements, acceptance hints, confidence, and any clarification questions.
3. A deterministic compiler checks every reference against the real project-plugin registry, chooses capability leases, pins each provider by plugin ID/version/operation/digest, and derives the authoritative acceptance, budget, and delivery contract.
4. Only then may Runtime prepare selected approved-catalog plugins, create the Run and immutable inputs, remove committed staging copies, and start the research loop.
5. After success, a task that requested a callable tool and has the publishing permission may use the controlled predictor-plugin path. A statically confirmed solver_bundle with that same permission instead uses the separate external-solver-adapter delivery path.

The planning model never receives raw attachment bytes, table rows, source bodies, or raw content from arbitrary archive members—only bounded, allowlisted static metadata. A native solver bundle is one explicit, bounded exception: backend profiling may read at most 64 KiB total from README/usage files and inspect bounded ELF, PE, or Mach-O headers. The README excerpt is labeled as untrusted user documentation and may be used only to infer the described command-line, input, and output contract; it is not a model instruction or execution authorization. Profiling neither runs the binary nor extracts the archive as a whole. The draft still cannot install or enable a plugin, select a concrete provider, grant a lease, create a Run, change a budget, or authorize execution. An attached ZIP or Python file is not silently installed as an existing plugin.

Capability suggestions are audit-only. Even an exact catalog suggestion cannot add a lease, select a generated tool, suppress the deterministic compatible match, or trigger installation. Unknown names, unnecessary executors, and other unselected suggestions are ignored and audited instead of invalidating a coherent task. An unmatched model-authored requirement is also an audit note; only requirements independently derived from checked intent and trusted inputs may stop creation as a missing capability. Generated-code reuse, persistent plugin generation, and bounded symbolic baseline fallback additionally require their separate UI/API permissions. All default off and are never inferred from prompt substring matching. First-time dependency preparation runs outside the API event loop, so Desktop remains responsive while the task button shows the preparation phase.

Acceptance hints remain advisory. Runtime independently parses the metric, comparison, numeric threshold, and trust requirement from the original request, and records every model hint as accepted or rejected in plan warnings. A model-only or trust-weakening threshold cannot become the acceptance gate.

After submission, Desktop opens a Planning Control Room immediately and projects decomposition into its timeline. If confidence is too low or a clarification is blocking, the page enters AWAITING INPUT: answer the displayed question or authorize reasonable defaults, then planning retries with a new idempotency identity. This is an input state, not a Control API error. No plugin changes, Research Run, input-artifact commit, training, or packaging occur before the contract is accepted. Staged attachments remain available. Model or schema failures remain visible as retryable planning failures, and Desktop never silently switches to keyword rules.

The successful autonomous-plan.json artifact records planning.source, prompt version, the validated draft, sanitized model calls, a stable model_provenance projection, and plan_digest, a SHA-256 over the canonical compiled plan payload. The digest binds the projected provider, model, context hash, and prompt version to the final leases, gates, effective budget, and deliverables; variable latency, token, retry, and request telemetry remains auditable but is deliberately outside the digest.

For a labeled tabular model, an explicit “within 5%” requirement becomes trusted relative_rmse <= 0.05. A lattice-survival model instead uses trusted binary classification, so the same ceiling becomes balanced_accuracy >= 0.95. A solver-source-only task has no independent labels to seal: its reference-solver error is marked untrusted and the plan also requires a checked routing policy and end-to-end speedup. Those two gates remain required even without an error threshold. In that case Runtime also owns the task_completion criterion; plugins and generated code cannot publish it, and Runtime records it only after required deliverables and final-predictor gates pass.

Solver benchmarks use the narrow reference-solver-benchmark-v1 protocol. The action must consume an immutable attachment whose role is reference_solver, report every non-Runtime criterion, and resolve exactly one model/inference.source.python pair plus one predictor output. The pair may be produced by that action or supplied together as declared Artifact inputs from an earlier training action. Runtime writes a separate predictor.evaluation receipt binding those artifacts, the benchmark result, and the solver by Artifact ID and SHA-256, but marks the receipt explicitly untrusted. It closes the freeze/publication lineage without pretending that agent-authored benchmark code is an independent evaluator. Supply independent labeled data when trusted error evidence is required.

CSV/TSV, JSON, Python source, common lattice text, directories, and ZIP receive bounded structural profiles; unknown formats remain opaque. Ordinary ZIPs expose member metadata; candidate solver ZIPs also receive the bounded README/native-header inspection above, still without execution or whole-archive extraction. Full hashes are checked again at commit. Valid staged files expire after 24 hours; damaged, tampered, or symlinked cache entries are retained rather than guessed at by recursive cleanup. Typical routing includes Xsuite for a lattice-tracking study, symbolic regression and reporting for candidate-formula discovery, or training plus an explicitly untrusted reference-solver benchmark for a solver-source-only surrogate. These are capability decisions based on the actual request and catalog, not fixed templates.

Use Choose folder to upload a directory. Web and Desktop mark it as source_kind=directory, validate a single root, and use fixed ZIP metadata only for immutable transport. Runtime reports directory_bundle, recognized source members, and allowed planner roles instead of zip_archive. The upload enforces at most 512 regular files, 50 MiB total before compression, a 10 MiB payload, 32 path components, and 1,024 UTF-8 path bytes. Unsafe paths, multiple roots, normalized duplicate paths, files that change while being read, and limit overruns are rejected before staging. Native Desktop selection also rejects symlinks and special filesystem entries. The WebUI accepts mixed file/folder drops and turns each top-level folder into one directory attachment; use the dedicated button when a browser does not expose dropped directory entries. At execution time Runtime checks the transport again and safely materializes a valid directory_bundle as a directory. Ordinary project capabilities and Local Executor programs receive that directory path rather than having to open the transport ZIP.

Runtime owns the generated program's command-line contract. If an action declares Artifact inputs without an explicit non-empty arguments list, Runtime deterministically derives --<logical-name> {artifact:<logical_name>} pairs and supplies the same contract to Code Author and Local Executor; training_npz, for example, becomes --training-npz. A directory bundle resolves to the safely extracted directory path. If generated or repaired Python uses argparse to require an option absent from Runtime's command, validation rejects that source and may use a bounded schema repair rather than waiting for execution to fail with a missing argument.

The Web File API exposes no Unix mode bits, so browser-created directory transports mark entries as ordinary non-executable files. This does not prevent a supported binary solver: after bounded, path-checked extraction into an isolated action workspace, the Runtime wrapper ensures that the executable selected by the plan can run and invokes only that path. Native Desktop packaging preserves available Unix execute bits on regular files. Unsafe paths, duplicates, symlinks, encrypted members, expansion risk, or a project-plugin manifest prevent a manually supplied archive from being promoted to solver_bundle.

The executable uploaded-lattice contract currently accepts only a data-only UTF-8 Xsuite Line.to_dict JSON mapping (optionally below a top-level line key). MAD-X, Elegant .lte, .seq, .tfs, and other lattice text are profiled but task creation stops with a missing-adapter error; Runtime never guesses a conversion or executes lattice source.

For tabular regression, Runtime seals the final split before the labeled upload enters research context. The Reasoner sees labeled training rows and target-free final inputs; only the allowlisted regression evaluator can read final targets. A predictor gets one final evaluation, while an exact retry replays the recorded result.

The current CSV convention uses the last column other than sample_id as the dependent variable; put the intended numeric target last. Runtime records that decision in sealed_holdout_targets. Formula search can rank several equations for that target, but does not yet infer another target from prose or sweep every column as the target.

Reusable tools

When the request explicitly asks for a callable or reusable tool, the plan may require an evaluated file-predictor-v1 model, inference source, exact evaluation artifact, model card, minimal example, usage guidance, and a reusable project plugin. Only Runtime's fixed publisher may wrap the accepted predictor artifacts into a digest-attested package. Control verifies the frozen model, inference, evaluation, accepted output, hashes, and recorded metrics against the package attestation before installation or export. The Reasoner cannot write the registry or turn arbitrary uploaded source into a plugin entrypoint.

A successfully published package has origin=generated, passes the managed install/worker checks, and becomes available to later tasks. Its model card drives conservative column-name/type matching; an ambiguous match is shown instead of silently selecting a tool. The result export includes the report, frozen model, example, instructions, and exactly the published plugin ZIP when applicable. Generated jobs may declare those two user-facing materials as MINIMAL_EXAMPLE and USAGE_GUIDE. Runtime accepts a minimal example only when it is a UTF-8, syntactically valid .py file containing actual executable usage code; the guide must be UTF-8 text that explicitly covers input, output, domain, and fallback. A file that fails these checks is not committed as a deliverable and cannot satisfy completion. Artifact-type input is case-insensitive, while stored and API values use the canonical spelling. A report-only analysis does not generate a plugin. If scientific work succeeds but publication or export fails, Control Room shows that delivery failure separately instead of claiming the package is ready.

Generated predictor inference runs as an ordinary child process in a dedicated action workspace on Linux, macOS, and Windows. Runtime filters credential variables and enforces timeouts, asset digests, and output limits, but the process retains the current user's filesystem/network authority. Ordinary Runtime-generated local jobs currently request 8,192 MiB of memory. On POSIX, Local Executor applies that address-space limit and classifies MemoryError, allocation failures, or a limited process killed by SIGKILL as memory failures. The generated-job default timeout grows from 300 seconds with declared solver-call cost, up to 7,200 seconds; an explicit action timeout still takes precedence.

A documented native solver uses a separate adapter publication path. Once static profiling confirms solver_bundle, check the existing Allow reusable plugin publishing permission to enter that path; wording such as “generate a plugin” cannot replace the typed authorization. From the untrusted README documentation, the Code Author may implement a standalone Python adapter that accepts --solver-root, --solver-executable, --input, and --output under file-solver-adapter-v1. Local Executor must run a bounded documented help/version or supplied example smoke test as a child process and record a passing result bound to the exact solver_bundle_sha256 and adapter_source_sha256.

The fixed runtime.solver_adapter.publish capability accepts exactly three immutable sources: the original bundle, adapter source, and validation artifact. It checks the validation record's declared pass state, interface, digests, and Artifact provenance; embedded and external attestations bind all three Artifact IDs/SHA-256 values and every package file. Control revalidates those identities before the ordinary managed install and worker-enable checks. If the same plugin ID/version is already installed, its installed attestation must also match. Neither the validation record nor attestation is independent proof that the smoke test actually ran. This adapter-only path does not invent a trained model or final predictor.

Those digests prove identity and lineage, not binary safety. ExternalBinarySecurityReviewer is a replaceable interface, and its current default decision is explicitly permissive_deferred: it allows publication while recording independent_binary_review_performed=false. No malware scan, signature validation, provenance authentication, or independent binary review has occurred. Both adapter validation and later calls through the installed plugin run with the current user's operating-system authority.

Advanced: explicit Research Contract

Use Advanced research contract, or open /create/advanced, when you need to choose every capability, criterion, workflow gate, and budget field. Only a contract that passes server-side preview can be created and started. The advanced page saves an unfinished draft on the device and can copy a previous run's configuration; inputs and global model settings are not copied. Its unfinished fields likewise survive page navigation for the current app session and are cleared after a successful start.

1. Research goal

• Task title — up to 120 characters, used in navigation and export names.
• What should this run establish? — a testable goal that names the object, scope, and desired result.
• Research questions — one per line. They guide the Reasoner but do not replace acceptance criteria.

For example:

Title: Reference ring boundary scan
Goal: Locate the positive-x survival/loss boundary after 128 turns
Question: What interval brackets the transition?

Avoid vague goals such as “study this data”; they do not define a useful stopping condition.

Copy configuration from a previous task copies goal, questions, workflow, capabilities, constraints, acceptance, and budget. Only capabilities still available are retained, and input files are cleared to prevent accidental data reuse.

2. Scientific workflow

These switches add optional completion requirements:

• Enable hypothesis verification permits versioned hypotheses, plans, approvals, verification requests, and results. Runtime rejects those actions when the switch is off.
• Require scientific artifacts for completion requires selected kinds in addition to all metrics: analysis_result, evidence, scientific_claim, hypothesis, verification_plan, verification_result, or scientific_report.
• Require reusable final predictor requires an evaluated model and inference program that obey the declared file-predictor-v1 input/output filenames.

Authorize pipeline selects installed Analysis, Knowledge, Verification, and Report capabilities in one operator action. It does not bypass permission review. CriteriaEngine still owns metric acceptance; artifact completeness is a separate additional gate.

3. Capabilities

Capabilities are grouped into domain experiments, execution/training, evaluation, analysis, knowledge/verification, and reporting/visualization. Selecting one authorizes the Reasoner to call it in this contract. Runtime rejects an unselected capability even when its plugin is installed.

Each card identifies its stable capability name, provider plugin, Core/Domain category, domain, trusted-metric status, scientific artifact flow, and declared output metrics.

Capability constraints is an advanced JSON field. For example, require evaluation datasets to use 128 turns:

{
  "beam.xsuite.generate_stability_dataset": [
    {
      "when": {"dataset_role": "evaluation"},
      "require": {"num_turns": 128}
    }
  ]
}

Each capability maps to a rule array; every rule contains only object-valued when and require. Leave {} when no constraint is needed.

4. Input artifacts

Import up to 20 files. CSV, JSON, and Parquet are classified as DATASET; Python files as source.python; other files as OTHER. Desktop imports bytes into ArtifactStore and does not persist the original host path.

Review name, type, and size. Preview computes a SHA-256, and each input becomes immutable after creation. Cross-action use is by Artifact ID; Runtime verifies run ownership, visibility, and hash before materializing an input into a plugin workspace.

5. Acceptance criteria

At least one criterion is required, and every criterion must be satisfied. Operators are >=, >, <=, <, and ==; one metric can appear only once.

Metric names come from selected capabilities' metric_outputs. Because generated programs may publish ordinary custom metrics through result.json, selecting the local executor also enables a custom metric name.

With Require trusted metric, a value from ordinary code or a solver cannot satisfy the criterion; a plugin declaring trusted_metrics must publish it. For example:

balanced_accuracy >= 0.90, trusted required

This prevents a training program from satisfying model-quality acceptance with its own claim.

6. Research budget

Desktop exposes Actions, Experiments, Failures, Solver calls, Training runs, Training samples, Model calls, and Model tokens. A blank field means “not set,” not zero. Unlimited budget removes every budget ceiling, but does not remove capability, policy, or acceptance checks.

Start with small but workable limits. When a limit is reached, the run becomes BUDGET_EXHAUSTED; its record is preserved, and the Control Room can raise that limit and resume atomically.

YAML also supports wall time, CPU/GPU hours, Reasoner calls/tokens, code generation/repair calls, and repair attempts. See Research configuration.

7. Review and start

Review Research Contract validates:

• goal, metrics, budgets, and file formats;
• enabled capabilities and possible metric producers;
• a trusted producer for each trusted criterion;
• model providers, profiles, and routing;
• workflow, final-predictor, and constraint consistency;
• uploaded file sizes and hashes.

Review plugins, capabilities, every criterion, models, executor, routing, input hashes, and warnings. Start Research first appends immutable RunCreated, then starts the background loop. To create without starting, use CLI new or separate Control API create/start calls.

Revising acceptance

Acceptance cannot change while a run is running. Pause it, then use State → Edit acceptance criteria. Saving creates an auditable revision and immediately reassesses existing evidence. A historical terminal status is not silently rewritten: a successful run that fails revised criteria is labeled as having completed under an earlier criterion.