Runtime Fabric, Skills, Tools, And Workspaces

SciDEX needs agents that can inspect artifacts, choose skills, run tools, edit source, review each other, and publish durable scientific work without turning any one repo into a monolith. This document defines the organizing model for that runtime fabric.

Ownership Model

Layer	Owner	Purpose
Agent reasoning	scidex-agents	Personas, roles, skills, adaptive tool-use policy, budget judgment, artifact authoring, review, critique, and improvement loops.
Registry/control plane	scidex-substrate	Artifact refs, tool metadata, runtime descriptors, schemas, job records, provenance, quotas, scores, leaderboards, permissions, lifecycle state, and public verbs.
Git collaboration plane	Forgejo / scidex-forge	Reviewable source repos, branches, commits, issues, PRs, releases, webhooks, and account/repo operations for living artifacts.
Presentation	scidex-prism	Transparent progress views, artifact graphs, leaderboards, runtime status, docs, and review dashboards.
Execution	agent runtime fabric	Containers, sandboxes, workspaces, tool invocation, result capture, and logs.

GitHub remains the platform source home for core SciDEX software repos. Forgejo is for SciDEX artifact collaboration and active scientific source history, not the substrate registry or the agent runtime state store.

Vocabulary

• Skill: a versioned reasoning/procedure bundle, usually a SKILL.md with small references or scripts. Skills say how an agent should think, decide, critique, spend budget, or operate a scientific workflow. Skills live in scidex-agents/skills unless they are still being reviewed as community artifact drafts.

• Tool: a callable capability with typed inputs and outputs. Examples: PubMed search, RDKit descriptor calculation, docking, AlphaFold lookup, dataset validation, benchmark scoring, or simulator invocation. Tool metadata and lifecycle live in substrate. Tool source may live in Forgejo or in an isolated agent-owned tool runtime.

• Runtime: the execution boundary that actually runs code. Runtime kinds can include local container, MCP server, HTTP service, bwrap subprocess, batch job, notebook worker, simulator service, or active artifact space.

• Workspace: an ephemeral per-agent/per-task filesystem where the runtime mounts skills, clones repos, stages source edits, loads tool bundles, writes scratch files, and captures results before publishing durable artifacts.

• Active artifact space: a long-lived or on-demand runnable artifact, similar to a Hugging Face Space: an app, simulator, benchmark dashboard, dataset browser, or leaderboard surface backed by a Forgejo repo and substrate runtime registration.

Repo Organization

Use Forgejo repos for reviewable scientific source, not private runtime scratch:

scidex-artifacts/
  paper-...
  hypothesis-...
  mission-...
  proposal-...

scidex-tools/
  pubmed-search/
  alphafold-lookup/
  rdkit-property-calculator/
  docking-pipeline/
  scanpy-qc-workflow/

scidex-spaces/
  protein-design-leaderboard/
  vaccine-design-arena/
  gbo-dataset-browser/
  synbio-construct-simulator/

scidex-benchmarks/
  kinase-binding-benchmark/
  perturbation-prediction-benchmark/

scidex-datasets/
  gbo-cortical-state-atlas-manifest/
  immune-aging-reference-panel/

scidex-submissions/
  challenge-<id>-agent-<id>-submission-<n>/

Core runtime code stays in scidex-agents. Forgejo-hosted source repos may contain tool bundles, active spaces, benchmark source, or living artifact source, but the generic runtime manager, workspace layout, persona loops, and skill selection policy stay here.

Runtime Manifests

Runnable Forgejo repos should carry a small manifest such as scidex-runtime.yaml:

artifact_ref: benchmark:kinase-binding
runtime_kind: space
entrypoint: app.py
image: forge.scidex.ai/scidex-spaces/kinase-binding:v1
ports: [7860]
resources:
  cpu: 8
  memory_gb: 32
  gpu: optional
inputs:
  - target_structure
  - design_submission
outputs:
  - scored_designs
  - leaderboard_update
substrate:
  registers_as: benchmark
  result_type: benchmark_result
  provenance_required: true
maintainers:
  - persona-jerome-lecoq
  - persona-karl-popper

Substrate registers the tool/runtime/space metadata and lifecycle state. Forgejo stores the reviewable implementation. Agents decide when to use or improve it.

Workspace Layout

Every concrete agent run should have a filesystem workspace with this shape:

/var/lib/scidex-agent/workspaces/<workspace_id>/
  workspace-readme.md
  manifests/
    workspace.json
    skill-catalog.json
  repos/          # Forgejo/Git working copies or local resource links
  artifacts/      # artifact source bundles and manifests
  tools/          # tool bundles or runtime descriptors
  results/        # staged output before substrate submission
  scratch/        # ephemeral computation files
  logs/           # run-local logs safe to back up
  state/          # run-local state, never secrets

Workspace state is recoverable operational evidence, but it is not the source of truth. Durable outputs must become substrate artifacts or Forgejo commits/PRs.

Agent Run Contract

The expected runtime flow is:

1. Agent reads substrate state, current work packets, budgets, and relevant refs.

2. Runtime prepares a workspace and records the skill/resource manifest.

3. Agent selects skills and tools based on context and expected value.

4. Runtime clones or links relevant Forgejo repos and resolves substrate tool descriptors.

5. Agent edits, runs code, analyzes data, and stages outputs in the workspace.

6. Results are submitted to substrate as artifacts/tool results with provenance.

7. Source changes go through Forgejo branches and PRs.

8. Reviewer agents critique, test, score, and request revisions.

9. Promotion updates substrate lifecycle, rankings, leaderboards, and Prism visibility.

This is a contract, not a fixed pipeline. Agents should inspect state at each step and adapt the order, effort, and compute spend to expected scientific value.

First Implementation

The first concrete runtime-fabric primitive is a workspace preparer:

./runtimectl workspace prepare \
  --agent-id persona-kris-ganjam \
  --workspace-id demo-kris \
  --resource artifact:hypothesis:example \
  --local-resource repo:agents=/home/ubuntu/scidex-agents \
  --json

It creates the standard workspace layout, writes a manifest, records the visible skill catalog, and materializes local resource links for runtime use. Provider runtimes such as Codex/Rosalind use the same workspace primitive before model execution, so future tools, spaces, and artifact repos can be attached without changing persona reasoning code.

Design Rules

• Do not put persona prompts, review rubrics, or budget policy in tool repos.

• Do not put tool metadata, lifecycle state, rankings, or ledgers in agent code.

• Do not put private runtime scratch in Forgejo unless it is intentionally promoted as a reviewable artifact.

• Do not make fixed trajectory pipelines. Encode goals, examples, checks, and contracts; let agents choose the next action.

• Prefer substrate refs and Forgejo PRs as handoff objects between agents.

• Treat the old Forge repo as a provisional tool-execution source until valid wrappers are registered in substrate and any surviving execution code has a bounded runtime home.