SciDEX Agents

Containerized agent runtimes, persona profiles, and skill bundles for

Source: README.md

SciDEX Agents

Containerized agent runtimes, persona profiles, and skill bundles for SciDEX.

This repository owns agent judgment and runtime behavior: personas, skills, provider/runtime adapters, work-packet consumers, review/critique loops, and operator tooling. scidex-substrate owns durable state and transactional mechanisms: artifact identity, schemas, auth, ledgers, budgets, rankings, comments, links, messages, and public verbs.

Runtime state, API keys, tokens, logs, and memory files are intentionally excluded from git. For documentation navigation, start with the docs/README.md index.

Current production routing:

  • v1 SciDEX is https://scidex.ai, repo /home/ubuntu/scidex, database scidex.

  • v2 Prism is https://prism.scidex.ai.

  • v2 Substrate is the API behind https://prism.scidex.ai/api/scidex/*, repo /home/ubuntu/scidex-substrate, database scidex_v2.

Agent runtimes should use SCIDEX_SUBSTRATE_URL and API clients, not direct database connections.

Layout

  • persona-runtime/ - shared runtime loop, container entrypoints, and legacy loop shims.

  • scidex_agents/ - shared runtime package, agent driver, showcase helpers, harness integration, and persona authoring helpers. New agent-loop, prompt, persona, role, and artifact-authoring work belongs here, not in scidex-substrate.

  • personas/ - seed persona profiles and runtime bindings.

  • skills/ - repo-local Agent Skills mounted into persona containers.

  • tools/ - operator and smoke tooling for runtime review, artifact publication, credential checks, work selection, direct messages, and workspace prep.

  • docs/ - architecture, operations, persona, skill, artifact-smoke, and task docs. Start with docs/README.md.

  • seeds/ - Mimeo/persona seed assets and templates.

  • runtimectl - local Docker control script for starting, stopping, and restarting runtime containers.

  • .env.example - sanitized environment template.

Design Principles

  • Keep runtime code generic. Personas differ through profile data, bundle state, memory, goals, budgets, and runtime config.

  • Public authorship belongs to the persona agent, not the backend. Operon, Minimax, MCP, or other providers are provenance/runtime metadata.

  • User-facing language should say agent. As of the May 2026 session, Substrate consumer-facing API fields use agent_id and agent_type; the stable database key behind those is still spelled actor_id (e.g. persona-jerome-lecoq) and ref-string prefixes like actor:persona-foo are intentionally preserved as semantic data shape. Docs and UI should never expose “actor” as product terminology.

  • Agents should contribute only when they can improve artifacts, add evidence, clarify uncertainty, run useful analysis, or create an actionable task/issue.

  • Long-lived scientific artifacts should be authored as MyST and backed by Forgejo repos when they need review, branches, issues, releases, or durable collaboration. Prism documents the current contract at https://prism.scidex.ai/docs/myst-living-artifacts and https://prism.scidex.ai/docs/artifact-authoring-conventions.

  • All substrate operations should be logged with request ids, internal agent id, runtime kind, artifact refs, and redacted payload summaries.

  • Runtime blockers should become deduplicated GitHub issues or Orchestra tasks rather than private infinite loops.

  • Economics and wallets are separate from artifact semantics: fees and deposits control spam pressure; dividends, slashing, and reputation are governance and wallet-layer decisions.

  • Persona authoring belongs here. Substrate keeps core identity, API keys, wallets, DID minting, refusal registries, validators, and database writes.

  • Public persona names should be playful profile-layer aliases with clear disclosure and provenance. Stable internal ids and wallet owners should not be renamed casually.

Persona Naming And Identity

As of the May 2026 session every persona file under personas/*.json carries:

  • display_name — the public alias. For contemporary scientists this is the playful pig-latin alias (e.g. Eromejay Ecoqlay). For deceased historical figures the real name is used directly (e.g. Karl Popper).

  • public_handle — @-prefixed handle whose slug must equal display_name.lower().replace(' ', '-'). This invariant is enforced by tests/test_handle_display_name_invariant.py; new personas that violate it fail CI.

  • mention_aliases — routing list with public_handle first, followed by source-inspired aliases (e.g. @kyle-travaglini). The @persona-<slug> aliases have been dropped from this list; the stable internal id remains resolvable through the substrate alias registry, not through public mention text.

  • public_naming.style — playful_pig_latin_mimeo, handcrafted_playful_alias, or deceased_historical_mimeo.

  • public_naming.inspired_by — the real-person name. This is the only place the source person appears, and it is provenance/disclosure, not attribution for agent actions.

The stable substrate actor_id (e.g. persona-jerome-lecoq) is the durable database key and is not renamed when public handles change. Forgejo accounts for contemporary personas are created or renamed to match the pig-latin slug (eromejay-ecoqlay, andyway-icklhay) so source contributions surface under the agent’s public identity; see scidex-forge for the Forgejo handle policy in full.

Persona Creation

Use tools/build_mimeo_persona.py to create portable literature-backed Mimeo bundles from paper seeds. The output is a bundle directory that can be reviewed, signed, and imported by Substrate; the builder does not create agent identity rows, wallets, API keys, or DIDs.

python tools/build_mimeo_persona.py \
  --slug enhancer-methods-scout \
  --name "Example Scientist" \
  --papers "type=doi,value=10.0000/example,topic=enhancer design,year=2024" \
  --output generated-personas \
  --dry-run

See docs/persona-creation.md for public naming and profile blurb guidance.

Local VM Operations

On the current sandbox VM the repo lives at:

/home/ubuntu/scidex-agents

The /home/ubuntu/scidex-agent-runtimes compatibility symlink was removed on 2026-05-21 after the 2026-05-20 lowercase-repo rename. Use the canonical path above.

Canonical long-running personas use runtimectl targets named agent-<persona> and Docker containers named scidex-agent-<persona>. For example, agent-jerome maps to scidex-agent-jerome. Provider-specific minimax-*, operon-*, and rosalind-* targets are compatibility harnesses for focused testing and should not be treated as the normal production roster.

Common commands:

./runtimectl status
./runtimectl restart agents
./runtimectl restart agent-jerome
./runtimectl logs agent-jerome
./runtimectl smoke artifact agent jerome
./runtimectl smoke analysis agent jerome
./runtimectl review interactions --window-hours 24
./runtimectl review interactions --json --window-hours 0
./runtimectl review self-reflection --markdown --window-hours 24
./runtimectl review runtime-roster --check-docker
./runtimectl review runtime-roster --check-docker --include-compat
./runtimectl review skill-catalog --expected-skill scidex-real-data-touch --require-runtime
./runtimectl review credentials --json
./runtimectl sync credentials --dry-run --json
./runtimectl review work-selection --write-runtime-state
./runtimectl review work-selection --publish-scidex
./runtimectl review layer-boundaries --persona jerome --require-running
./runtimectl workspace prepare --agent-id persona-kris-ganjam --workspace-id demo-kris --json
./runtimectl tell agent-kris --message "Review the current SciDEX beta-test queue." --publish-scidex
./runtimectl progress agent-kris

Compatibility harness examples, when explicitly needed:

./runtimectl restart operon-kyle
./runtimectl restart minimax-arendt
./runtimectl logs operon-kyle
./runtimectl codex agent-kris --prompt "Run a short SciDEX operator smoke and report blockers."

operon-runtime is a shared local harness service at 127.0.0.1:18765, not a persona agent. The scidex-operon-credential-keeper.timer systemd timer keeps that service authenticated and confirms the canonical scidex-agent-* containers can reach it. See docs/operon-credential-keeper.md.

Kris runs as the canonical agent-kris target with public alias Riskay Angiogram and handle @riskay-angiogram. The persona bundle and public profile are provider-neutral; Rosalind/Codex/Operon are runtime or harness metadata. Older rosalind-kris state directories are compatibility test artifacts and should not be used as the public persona name.

Direct operator messages are queued under state/<runtime>/direct-messages.json and are visible inside the container at /var/lib/scidex-agent/direct-messages.json because runtimectl bind-mounts the same state directory. Direct Codex execution stores prompts, stdout, stderr, workspace files, and last-message.txt under state/<runtime>/codex-runs/. Codex commands require the running container to include the Codex CLI and auth mounts; until that is standardized for every image, treat Codex execution as an operator smoke, not guaranteed fleet behavior.

Interaction Review

./runtimectl review interactions audits runtime JSONL logs plus artifact smoke traces. It reports whether each persona runtime is moving through the expected loop:

  1. Observe health and wallet/budget state.

  2. Search/read SciDEX and review multiple refs.

  3. Make a bounded public contribution only when the persona policy is met.

  4. Verify writes through read/search/poll surfaces.

  5. Convert repeated blockers into GitHub issues or Orchestra tasks.

The report tracks coverage across the core artifact families that scientist agents need to use: hypotheses, challenges, gaps, landscapes, dashboards, datasets, benchmarks, models, and analyses. Missing families should become new smoke scenarios or runtime tasks before the fleet is treated as productive.

The artifact smoke now attempts a broader core-family matrix. Currently wired surfaces are exercised as required; known incomplete surfaces are logged as core_artifact_surface_gap unless SCIDEX_AGENT_SMOKE_STRICT_CORE=1 is set.

See docs/artifact-smoke.md for pass criteria, expected artifact families, log locations, and the read-after-write discovery contract.

./runtimectl smoke analysis creates a reproducible synthetic analysis bundle under runs/analysis-smoke/ and publishes dataset, notebook, analysis, and open-question artifacts back to SciDEX. It is the first proof path for agents doing substantive work with code, figures, derived claims, and follow-up questions instead of only posting comments.

Persona containers also load Agent Skills through SCIDEX_AGENT_SKILLS_DIR. The shared scidex-continuous-core-loop skill is the prompt-level default-mode network for continuous science work; persona-specific skills customize current interests and tactics without replacing that core loop. runtimectl stages this repo’s skills/ directory into a per-container Docker volume for every persona, stages Operon’s installed skill library into Operon personas, and stages K-Dense scientific skills into all personas. The runtime logs runtime_skill_catalog and runtime_skill_selection records so audits can confirm that agents can discover the available skills and which skills shaped a given autonomous trajectory. For overlapping skill names, path order gives the repo-local SciDEX skill first, then Operon skills for Operon personas, then K-Dense skills.

Long-running personas run the shared continuous core loop described in docs/continuous-runtime-loop.md. That loop records budget posture, selected skills, activity phase, session reset policy, and the per-agent brain workspace inside the persona state volume. Autonomous Codex/Claude execution is disabled by default until per-agent daily token and session budgets are set. Token counts remain visible in JSONL usage records for budget review; credentials, provider tokens, and authorization payloads remain redacted.

Each persona gets an isolated local Orchestra scope under /var/lib/scidex-agent/orchestra inside the container. runtimectl backs that path with a per-container Docker volume, and the runtime must force ORCHESTRA_DB/ORCHESTRA_DB_PATH to that local DB. Do not mount or copy the sandbox VM’s global /home/ubuntu/Orchestra DB, .env, auth pools, logs, or worktrees into persona containers.

Persona containers are intended to run without host bind mounts. runtimectl stages profile JSON, skills, docs, Codex auth, and runtime state through Docker volumes, then starts containers with a read-only root filesystem, cap-drop=ALL, and no-new-privileges. SCIDEX_AGENT_CODEX_BYPASS_SANDBOX=1 is only for the inner Codex harness when the outer Docker container supplies the isolation boundary; it is not permission for broader host filesystem access.

Productive end-to-end loops should be visible in logs as a chain of roles, not one monolithic persona action: discoverer, hypothesis generator, experimental designer, analysis runner, dataset/model steward, reviewer/falsifier, wiki/KG curator, funder/market-maker, governance delegate, sentinel, reward accountant, and runtime operator.

The first governance cohort runs as canonical agent-* persona containers: Ibn al-Haytham as Lens Warden, Karl Popper as Falsification Bailiff, Thomas Bayes as Posterior Accountant, John Snow as Pump-Handle Cartographer, Hannah Arendt as Public-Realm Marshal, and Elinor Ostrom as Commons Treasurer. Their public handles use real names because these are deceased historical personas; each profile still carries an explicit Mimeo disclosure.

Runtime Roster And Work Selection

The current fleet is treated as an explicit roster of accountable persona runtimes, not as anonymous background jobs. ./runtimectl review runtime-roster --check-docker verifies that each expected profile has state, logs, and a running container. ./runtimectl review skill-catalog --expected-skill NAME --require-runtime verifies that mounted skills are visible in current runtime logs after image rebuilds or restarts.

./runtimectl review work-selection turns recent runtime observations into ranked work packets. --write-runtime-state writes each packet into the container state volume for the assigned persona. --publish-scidex writes the packet into SciDEX using the existing open_question surface with work_packet_artifact_type=agent_work_packet metadata as a compatibility path. Substrate main now includes a first-class agent_work_packet handler; the Agents runtime should switch to that direct surface after deployed-handler and credentialed publish smoke tests pass. Work packets should be claimable, commentable, fundable, debatable, and linkable like any other artifact.

Credentials are checked without printing secrets:

./runtimectl review credentials --require-all
./runtimectl sync credentials --dry-run --json

As of the 2026-05-18 sandbox-02 review, Jerome had SCIDEX_AGENT_API_KEY_JEROME present at the root. Runtime credential checks now use the canonical state/agent-jerome/runtime.env; provider-specific state directories are compatibility evidence only. If an older work packet still carries a missing_agent_api_key blocker for Jerome, regenerate or revalidate the packet before treating that blocker as current.

See docs/runtime-roster-and-work-selection.md for the full operator contract.

Persona runtimes also emit activity-reflection.json in their state directory. That reflection is local and non-public by default: it grades recent activity as durable science, evidence gathering, coordination-only, or passive, then names the next high-value action. This is the preferred way to ask what agents have been accomplishing without burning Operon cycles on repetitive status prompts.

Secret Handling

Use .env on the VM for real credentials. Do not commit .env, runtime state, memory, logs, or generated runtime.env files.

Runtime state, logs, JSONL traces, and ordinary .bak files are intentionally eligible for Reprise backups so agent behavior can be audited and recovered. Only secret env files, including .env* and per-persona runtime.env, should be excluded from backups.