Durable collaboration sessions

An external assistant can use an existing Biosimulant chat as the durable record of its work. The assistant reasons and orchestrates. Biosimulant stores approved requirements, versioned plans, exact workspace revisions, validation evidence and human decisions. No second reasoning agent runs when these tools are used.

The session is the existing chat, not a separate Task. Research-only questions can start without a Lab or compute. A workspace-created chat already has a session: use the session_id returned by workspace_create or workspace_get, or find it with session_list.

Start or resume

1. Find the existing chat with session_list, or use session_create with a stable creation key.
2. Use session_attach to map your external conversation ID to the chat. Mappings belong to the caller and client; they grant no additional permissions.
3. Call session_resume before changing work. It returns the approved contract, current plan, criteria, validation receipts, pending approvals, scientific workflow state, current workspace revision, remaining run count and a sequence cursor.
4. When files are needed, use session_workspace_create to create or reuse this chat’s one private workspace. This starts no compute.

The Evidence panel in the chat shows session requirements, full proposals and scientific reviews. Its copy button provides a resume instruction for another assistant. Different sessions and tools can retrieve the same approved state; execution grants remain specific to each client.

Requirements and plans

session_contract_prepare accepts a goal, intended use, scope, criteria, advisory guidance snapshots and an optional max_runs limit. Guidance content is stored with a server-computed SHA-256; later global guide changes cannot silently replace it. A criterion uses a supported versioned passport_check on an exact workspace revision, or an explicit human_review. Unsupported automatic validators are rejected.

Approve the full exact proposal in Biosimulant, then let the originating client call session_change_apply with its plan_id and plan_sha256. Plans expire, are client-bound, and cannot be applied if the requirements, plan progress or workspace have changed. Approval of the contract is separate from authorization to execute compute or publish.

Once requirements are approved, session_plan_prepare proposes up to twenty ordered steps, with earlier-step dependencies and criterion IDs. Approval and apply create a normal versioned chat plan without invoking the internal chat agent. Revising the approach does not rewrite requirements; a contract change needs its own approval and invalidates the old plan and acceptance receipts.

session_progress_update records active, done, failed or skipped for a step of the current approved plan. It uses the latest sequence and rejects stale writers, unfinished dependencies, a second active step, and another client’s execution authority. A failed step can be retried; reopening a finished or skipped step requires a new plan. Skipped steps do not count as successful completion.

For sessions with approved contracts, Gateway workspace changes and managed runs require an active step in this client’s approved plan. Runs retain the exact session, contract, plan and step IDs in their execution metadata. Other clients may resume and propose their own approved plan; they do not inherit consent.

Validation and completion

session_validation_submit evaluates a managed run’s server-owned Evidence Passport against the approved exact revision, quality-profile version and check ID. It records the Passport digest, validator identity and check result. PASS passes that criterion; warnings, missing checks and unevaluated checks do not. Managed validation also requires runs:read and passports:read.

An imported agent report remains pending human review. The authenticated user can accept or reject a human-review criterion in the chat, with an explicit rationale recorded as a new receipt. External agents and Developer API keys cannot create human review decisions. Scientific judgment and unsupported biological accuracy claims are not manufactured as automatic passes.

session_completion_check establishes acceptance only when all required criteria pass, all plan steps are done, the plan belongs to the current contract, and each approved workspace revision remains active. Otherwise it returns blockers. Publication through the Gateway and Chat is blocked for governed sessions until that same acceptance gate passes; publication still requires its existing exact approval and permissions.

The optional run cap counts all persisted workspace runs, including failed and deleted runs, across contract revisions. A session lock checks capacity in the shared revision-run transaction, covering Chat, MCP, API and study arms. It is a run-count budget; it is not a currency-spend limit and does not authorize hosting or unrelated release runs.

Boundaries and retention

Biosimulant governs operations through its services. It cannot control an external host’s chat or actions through unrelated tools. General guidance remains advisory; approved requirements and service permission checks are authoritative for governed operations.

Archive preserves the collaboration record and prevents external writes until the chat is unarchived. Chat deletion uses existing soft deletion. New contracts and receipts restrict cascading hard deletion of their scientific records; a future retention migration must be explicit. Permissions continue to follow personal ownership and current team membership.

All session tools have matching Developer API routes. Reads use workspaces:read; writes use workspaces:write. Mutations also honor the Gateway switch and client allowlist. The human review endpoint belongs to the authenticated chat UI, not the agent API.