Building an “Open AI for Scientist” from scratch (OpenAI4S lineage) · full development tutorial

0.1 One-sentence product

Open AI for Scientist (OpenAI4S): a hybrid scientific-agent workbench that runs on the scientist’s own computer—using a cheap Doubao / Ark API (even the ¥9.9/month tier works), it closes the loop from literature/database retrieval, data analysis, and visualization to a reproducible evidence pack; not another programming IDE Agent, and not multi-tenant SaaS.

0.2 Persona

0.3 Jobs-to-be-done

1. Retrieve and land evidence: query UniProt / RCSB / PubChem / arXiv; results must be hashable and archivable.
2. Compute in a persistent environment: multi-step pandas/scanpy/RDKit analysis must not collapse because “every step opens a new process.”
3. Leave an auditable trace: every tool/Cell step enters the ledger; dangerous operations pop an approval card.
4. Deliver a shareable pack: export a session / evidence pack to collaborators, not a screenshot of chat.
5. Affordable: default to Volcano Ark ark; the ¥9.9 Small plan can run the main path.

0.4 Non-goals (write them into the PRD or they will not block scope creep)

0.5 Success metrics

0.6 Constraints

• Models: prefer Volcano Ark (Doubao etc.); also support OpenAI / Anthropic / Gemini lines; keys never enter the repo.
• Platforms: macOS (Apple Silicon first-class) + Linux x86_64; Windows = WSL2.
• Runtime: Python 3.10+; core pure stdlib; the scientific stack goes into the kernel environment, not the control-plane venv.
• Data root: ~/.openai4s (overridable with OPENAI4S_DATA_DIR).
• Compliance tone: biosecurity screening on by default; telemetry off by default and requires consent.

0.7 MVP vs v0.1

0.8 The walls hidden in that one sentence

Our first user story:

"Look up human insulin INS, pull sequence and structure from UniProt/RCSB, draw a simple figure, save the result as a reproducible artifact, and summarize in Chinese."

0.9 Write the PRD as executable milestones (suggested schedule)

0.10 Product principles (used to veto requirements while writing code)

1. The ledger is truth; the UI is a projection. Any PR that “only changes the frontend and calls it done” is sent back.
2. Control plane and scientific plane do not race. One step walks one channel.
3. Wrong provenance is worse than missing. If you do not know, write the missing reason.
4. No subscriber must not default to allow. A security event cannot be released because “nobody is looking at the card.”
5. Core zero-dependency is a constraint, not a style. Want to add httpx/fastapi? First write why urllib/http.server cannot do it.

✅ This step’s acceptance: you can tell an investor / lab PI in 90 seconds: two planes, stdlib daemon, not an IDE, not SaaS, ¥9.9, macOS+Linux.

Purpose

Turn PRD boundaries into directory ownership. Later OpenAI4S crashes are 80% “new capability stuffed into the wrong package”: GPU provider written into skills/, SQL written into gateway.py, the completion contract registered as an ordinary Tool.

Implementation shape

Target tree (against 85e9fa0):

openai4s/
  agent/          # 外环：engine、ports、actions、ledger、compaction、delegation
  kernel/         # 内环：manager、worker、lazy、r_kernel、sandbox 协作
  sdk/            # 注入到 worker 的 host 门面
  host/           # 能力实现（files/llm/delegation/…）
  host_dispatch.py
  llm/            # urllib 多供应商
  tools/          # Native JSON Tool 子类 + registry
  store.py        # SQLite 门面
  storage/        # repositories + migrations
  server/         # gateway、SessionRunner、webui/
  skills_loader/  # 配方加载
  compute/        # BYOC 宿主侧（后期）
  security/       # 分层策略
  config.py prompts.py …
skills/           # 内置配方（数据，不是引擎）
envs/             # conda/micromamba 环境定义
openai4s_compute_provider/  # 远程侧 stdlib worker SDK

Stack

• Python 3.10+ package layout + pyproject.toml / setuptools
• Forbid hard third-party imports in the core package (numpy etc. only on the kernel side or behind try/except ImportError)

Definition trade-offs

Strengths and costs

• Strength: CI and review have an answer to “where does this go”; mypy can be strict only on agent/{engine,ports,…} + host_dispatch.py.
• Cost: many directories for newcomers; you need bilingual READMEs as gates (OpenAI4S does exactly that).

How it couples to previous and later modules

• Before: PRD non-goals directly decide “there is no ide/, no saas/.”
• After: step 2 config, step 4 engine, step 11 server all hang on this tree.

flowchart LR
    PRD["PRD boundaries"] --> PKG["package ownership table"]
    PKG --> AGENT["agent outer loop"]
    PKG --> KER["kernel inner loop"]
    PKG --> TOOLS["tools control plane"]
    PKG --> SRV["server projection"]
    PKG --> DATA["skills/envs data"]

1.4 Week-one minimum runnable skeleton (suggested files to create now)

pyproject.toml
openai4s/__init__.py
openai4s/__main__.py
openai4s/config.py
openai4s/agent/{__init__,ports,models,events,actions,engine}.py
openai4s/llm/{__init__,client,transport,registry}.py
openai4s/tools/{__init__,base,registry}.py
openai4s/host_dispatch.py
openai4s/sdk/host.py
openai4s/kernel/{manager,worker,lazy}.py
openai4s/store.py
openai4s/server/{gateway.py,webui/index.html,webui/app.js,webui/style.css}
tests/test_agent_route_action.py

First let python -m openai4s print a version; then let AgentEngine run finalize under FakeModel. Do not start by beautifying the WebUI.

1.5 Ownership-table example (pin it on the wall)

✅ This step’s acceptance: draw a table of where “new Tool / new Host capability / new SQL / new UI route” land; pick one wrong landing and explain the consequence.

Purpose

Before writing the LLM, decide: where keys come from, where data is written, which port the process binds. Scientific users will configure models from the UI and also use .env; the two must not step on each other.

Implementation shape

• openai4s/config.py: Config / LLMConfig dataclass + zero-dep .env loading
• Env-var layering: OPENAI4S_<PROVIDER>_API_KEY → OPENAI4S_LLM_API_KEY → provider default
• Data root: ~/.openai4s/{logs,artifacts,tool-results,compaction-history,openai4s.db,agent-workspaces,…}
• Port: OPENAI4S_HOST=127.0.0.1, OPENAI4S_PORT=8760

Stack

• dataclasses + os.environ + a hand-written dotenv (do not pull in python-dotenv)

Definition trade-offs

Strengths and costs

• Strength: Ark / Claude / Gemini keys can coexist; tests can point OPENAI4S_DATA_DIR at tmp.
• Cost: when debugging layered resolution you must print “which layer actually hit.”

How it couples to previous and later modules

• After: LLM client (step 3) and Store paths (step 8); Gateway reads the same Config.

flowchart TD
    ENV["real environment variables"] --> RES["LLMConfig resolve"]
    DOT[".env does not override existing"] --> RES
    RES --> KEY["api_key / base_url / model"]
    RES --> CFG["Config.data_dir / host / port"]
    CFG --> DB["db_path"]
    CFG --> WS["agent-workspaces"]

✅ This step’s acceptance: with only OPENAI4S_ARK_API_KEY set, provider=ark can read it; a template placeholder is judged as no key.

Purpose

A scientist’s key may be Ark, DeepSeek, or official Claude/GPT/Gemini. The product must switch providers in one line, but cannot pull a dependency for every SDK—the core must stay pure stdlib.

Implementation shape

openai4s/llm/
  client.py          # chat() 编排入口
  transport.py       # urllib 的 post_json / post_sse
  registry.py        # PROVIDERS 目录（wire/model/base_url）
  providers/
    openai.py        # Chat Completions
    responses.py     # OpenAI Responses
    anthropic.py     # Messages
    gemini.py        # generateContent
  tooling.py messages.py capabilities.py catalog.py

Outward compatibility façade: from openai4s.llm import chat.

Stack

• urllib.request + SSE line parsing
• Unified normalization: ModelReply / tool_calls (keep raw_arguments + parse_error + provider_meta)

Definition trade-offs

Strengths and costs

• Strength: small package; offline tests can mock the whole transport; the Ark ¥9.9 path has zero friction.
• Cost: SSE/error codes must be aligned to each vendor’s docs yourself; strict schema differences need a capability buffer.

How it couples to previous and later modules

• Before: Config resolves the key.
• After: AgentEngine’s ModelPort wraps a ChatModel; Host’s host.llm also walks the same chat().

sequenceDiagram
    participant E as AgentEngine
    participant C as llm.chat
    participant T as transport.urllib
    participant P as Provider API
    E->>C: messages + tools + on_delta
    C->>C: provider_spec + capabilities
    C->>T: post_sse / post_json
    T->>P: HTTPS
    P-->>T: SSE chunks
    T-->>C: deltas + final
    C-->>E: ModelReply(tool_calls|content)

3.4 Minimal chat() shape (the contract you freeze first)

# 教学简化版 —— 生产代码见 openai4s/llm/client.py
def chat(messages, cfg, *, on_delta=None, tools=None, post_sse, post_json):
    spec = provider_spec(cfg.provider)
    wire = spec["wire"]          # openai | responses | anthropic | gemini
    model = cfg.model or spec["model"]
    base = cfg.base_url or spec["base_url"]
    # 1) capability 门闩  2) 译 tool specs  3) 调对应 wire
    return wire_dispatch[wire](...)

The return value must be ingestible by ModelReply.from_mapping, at least including:

• content: str
• tool_calls: list[{id, wire_id, name, ordinal, raw_arguments, arguments, parse_error, provider_meta}]
• usage: {prompt_tokens, completion_tokens}

Trade-off: keep raw_arguments and parse_error together—the routing layer is a lossless boundary, not a second JSON parser. Parse failures still enter the Ledger; they must not be silently dropped.

3.5 Why Ark walks the OpenAI-compatible wire

Volcano Ark Agent Plan exposes an OpenAI Chat compatible endpoint. You put provider=ark in the registry, reuse providers/openai.py, and only change the default base_url/model catalog. That way the ¥9.9 path needs no third protocol implementation.

✅ This step’s acceptance: against a fake transport, assert that ark and anthropic both produce the same shape of tool_calls; when there is no key, the error message points at the correct env-var name.

Purpose

Write an outer-loop state machine that is unit-testable and does not depend on kernel/server. This is the spine of the whole product: CLI openai4s run and Web SessionRunner._loop must share it, or the two loops will drift.

Implementation shape

• agent/ports.py: ModelPort / ActionExecutor / ContextPolicy / EventSink / CancellationPort / CompletionPort / ReplyInterceptor
• agent/engine.py: AgentEngine.run turn loop
• agent/actions.py: route_action, CodeCell, NativeToolBatch, FinalizeAction
• agent/models.py: RunState / ModelReply / ExecutionOutcome / EngineResult
• agent/events.py: RunStarted…RunFinished

The core loop (semantically compressed):

while turn < max_turns:
  prepare context
  reply = model.complete(messages, on_delta)
  action = route_action(reply.content, reply.tool_calls)
  outcome = executor.execute(action, reply, state)
  append history
  if outcome.stop_reason or completion: break

route_action iron laws:

1. The sole native call and it is named finalize_response → FinalizeAction
2. Otherwise, if there is any native call → NativeToolBatch (whole batch; control plane first)
3. Otherwise extract the first complete python /r Cell from the body
4. None of the above → None (upper layer nudges)

Stack

• Pure typing Protocol + dataclass; mypy strict on these files

Definition trade-offs

Strengths and costs

• Strength: the engine can test routing and terminal states with no network and no subprocess; Web/CLI only swap adapters.
• Cost: if the model “talks and writes two Cells,” they are trimmed; you need the prompt and nudges to teach it.

How it couples to previous and later modules

• Before: LLM ModelReply.
• After: the Executor is assembled by agent/runtime.py on CLI and by WebActionExecutor on Web; real work goes into Host/Kernel.

flowchart TD
    R["ModelReply"] --> RA{"route_action"}
    RA -->|"sole finalize_response"| F["FinalizeAction"]
    RA -->|"other native calls"| B["NativeToolBatch"]
    RA -->|"no native"| X{"extract_action"}
    X -->|python/r fence| C["CodeCell"]
    X -->|none| N["None → nudge"]
    F --> EX["ActionExecutor"]
    B --> EX
    C --> EX
    N --> EX

4.4 FakeModel-driven first tests (suggested to land as written)

class FakeModel:
    def __init__(self, replies):
        self.replies = list(replies)
    def complete(self, messages, on_delta):
        reply = self.replies.pop(0)
        if on_delta and reply.get("content"):
            on_delta(reply["content"])
        return reply

class FakeExecutor:
    def execute(self, action, reply, state):
        # 断言 action 类型，然后返回 ExecutionOutcome(stop_reason=...)
        ...

Test first:

1. Sole finalize_response → stop reason is completion;
2. web_search + ```python in the body → walk the batch, do not run code;
3. Two python Cells in the body → extract only the first;
4. Unclosed ```python → do not execute + nudge.

Wait until these four are green before wiring real HTTP.

4.5 Micro-timing of one turn inside the engine

sequenceDiagram
    participant P as ContextPolicy
    participant M as ModelPort
    participant R as route_action
    participant X as ActionExecutor
    participant S as EventSink
    P->>P: prepare(messages)
    M->>S: TextDelta*
    M->>R: ModelReply
    R->>X: Action|None
    X->>S: OutcomeProduced
    alt stop/completion
      X-->>P: EngineResult
    else continue
      X->>P: history appended, next turn
    end

✅ This step’s acceptance: pure unit tests cover: finalize first, tools beat code, only the first of multiple Cells, unclosed fences do not execute.

Purpose

Wherever a call comes from—a native Tool, or host.web_search inside a Cell—it must pass through the same permission / approval / audit / injection-screen / activity-event envelope. Otherwise you will own two inconsistent security stories.

Implementation shape

• openai4s/host_dispatch.py: HostDispatcher.__call__(method, args) -> data
• openai4s/host/*.py: WorkspaceFileService, LLMService, DelegationService, CompletionService, SkillService…
• soft-fail: {"error": msg} → worker turns it into RuntimeError

Stack

• Thread lock + optional ThreadPoolExecutor (read-only tool parallel waves live on the control executor side)
• Collaborates with tools.registry.get_tool_by_host_method

Definition trade-offs

Strengths and costs

• Strength: one point for audit and permission; Web control tools and kernel RPC share policy.
• Cost: the façade is still large; refactors must be “surgery”; forbid whole-file rewrites.

How it couples to previous and later modules

• After: the SDK only sends host_call; the Kernel manager calls the Dispatcher; the Ledger records audit.

flowchart LR
    A["Tool.invoke / host.*"] --> D["HostDispatcher"]
    D --> P["permission / approval"]
    D --> I["injection screen"]
    D --> S["host service"]
    D --> L["audit / step event"]
    S --> OUT["data | {error}"]

✅ This step’s acceptance: the same web_fetch entering from a Tool and from host.web_fetch has matching approval and audit fields.

Purpose

Let scientific code call host capabilities synchronously mid-Cell: host.llm, host.delegate, host.save_artifact… This is the inner loop that a tool_use architecture does not have.

Implementation shape

• openai4s/sdk/host.py: in-worker host singleton façade
• Inject a host_call(method, args) callback when starting the worker
• Codec: SDK snake_case ↔ wire camelCase; omit None fields (avoid JSON null hitting strict validation)
• host.bash: does not execute shell on the Host; Host only issues a one-shot token bound to command hash / cwd / generation / challenge; the worker executes locally

Stack

• Pure Python façade; no third party
• HOST_CAPABILITY_VERSION written into the bootstrap manifest for restore comparison

Definition trade-offs

Strengths and costs

• Strength: scientists compose capabilities with for/if/libraries; large objects never enter the prompt.
• Cost: deadlock risk—must have a single in-flight host_call lock + a single reader loop.

How it couples to previous and later modules

• Before: Dispatcher.
• After: Kernel protocol frames host_call / host_ack / host_response.

sequenceDiagram
    participant Cell as Python Cell
    participant SDK as host SDK
    participant W as worker.py
    participant M as Kernel manager
    participant H as HostDispatcher
    Cell->>SDK: host.web_search(...)
    SDK->>W: host_call frame
    W->>M: stdout protocol line
    M->>H: dispatch(method,args)
    H-->>M: data
    M->>W: host_response
    W-->>SDK: return
    SDK-->>Cell: result

✅ This step’s acceptance: in a test kernel, execute host.submit_output({"ok": True}, completion_bullets=["done"]), outer-loop stop_reason=submitted.

Purpose

Land the scientific plane: Tool/Finalize-only turns do not start a worker; the first Cell lazily pulls one up; the namespace persists across Cells; stdout and protocol are split; an OS sandbox constrains write paths and the naked network.

Implementation shape

• kernel/manager.py: Kernel on the host side, spawn + single-thread frame reader
• kernel/worker.py: Python worker; compile(..., "<kernel:N>") + linecache; getrusage accounting
• kernel/lazy.py: CLI one-shot lazy ownership
• kernel/r_kernel.py + r_worker.R: same protocol; protocol on fd3/fd4, noise to stderr
• kernel/environment.py: subprocess env rebuilt from an allowlist (does not inherit daemon keys)
• security/sandbox.py: macOS Seatbelt / Linux bubblewrap; auto|enforce|off

Protocol (concept):

{"type":"execute","id":"...","code":"..."}
{"type":"host_call","id":"...","method":"web_search","args":[...]}
{"type":"host_ack","id":"..."}
{"type":"host_response","id":"...","data":{...}}
{"type":"result","id":"...","ok":true,"stdout":"..."}

Stack

• subprocess + JSON lines
• POSIX redirect (R); Seatbelt / bwrap

Definition trade-offs

Strengths and costs

• Strength: Code-as-Action collapses 14 tool round-trips into 1 Cell; in-memory state is reusable.
• Cost: crash recovery, generation ABA, and watchdog all have to be done seriously (see step 17).

How it couples to previous and later modules

• Artifact provenance binds to kernel generation, not the daemon process’s package list.
• The security layer (step 19) stacks on the spawn boundary.

flowchart TB
    T["Tool/Finalize turn"] -->|do not spawn| Z["no worker"]
    C["first Python Cell"] --> L["Lazy start python slot"]
    R["first R Cell"] --> LR["Lazy start R slot"]
    L --> SB["sandbox wrap"]
    SB --> W["worker subprocess"]
    W --> NS["persistent globals"]
    W --> RPC["mid-cell host RPC"]

7.4 Three iron laws when implementing the protocol

1. Single reader: only the Kernel manager thread reads worker stdout; supervisor/watchdog must not sneak a read.
2. Single in-flight host_call: the worker holds a lock through host_call → host_response; concurrent RPC will interleave frames.
3. generation is monotonic: every respawn bumps generation; tokens/leases/approvals bound to the old generation must fail.

7.5 Minimal worker pseudocode

# worker.py 概念版
for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "execute":
        # 重定向 stdout 到捕获缓冲，协议帧走另一条通道
        try:
            exec(compile(msg["code"], f"<kernel:{n}>", "exec"), ns)
            send({"type": "result", "id": msg["id"], "ok": True, "stdout": buf})
        except Exception as e:
            send({"type": "result", "id": msg["id"], "ok": False, "error": ...})

The Host SDK’s host_call must walk a channel separated from stdout capture, or print and RPC smash each other.

✅ This step’s acceptance: two consecutive Cells, the second can read the first’s variables; a pure finalize turn has no worker in the process list.

⚠️ Not done yet: protocol anti-pollution and provenance taste are in step 7.5; that is where this tutorial parts ways with “ordinary Agent tutorials.”

Purpose

Step 7 made the kernel “able to run.” This step makes you understand why the author wrote the worker that way—this is the physical landing of OpenAI4S taste. Against source: kernel/worker.py file header, manager.py single reader, CLAUDE.md “wrong provenance is worse than none.”

Lab A · Protocol split (required thought experiment)

Suppose you are lazy: protocol and print share fd1.

1. The model Cell does print(huge_df);
2. At the same time host.web_search(...) sends host_call;
3. The manager’s readline() reads a half table → JSON dies → the whole session hangs.

OpenAI4S’s solution:

• Python: dup2(2,1) + a high protocol fd published to sys._openai4s_protocol_* (resolve again on every call; caching forbidden);
• R: protocol on fd3/fd4, noise to stderr.

Trade-off: the protocol implementation becomes “ugly”; product behavior becomes “dull-correct.”

Lab B · The frame cap is not a guess

Read the _MAX_FRAME_BYTES comment chain in worker.py:

• First there was a character cap MAX_OUTPUT;
• Then it was found that UTF-8 / \uXXXX / emoji surrogate pairs make “bytes” far larger than “characters”;
• The constant was revised from a wrong 6 to 12 bytes/character worst case, and tests nail it down.

Taste lesson: a scientific Agent’s users will type Chinese, molecular formulas, emoji comments. The cap must be derived from the worst character, or you will lose error_lineno and usage while “looking like you obeyed the docs”—again “wrong is worse than none.”

Lab C · Single in-flight RPC and generation

flowchart TB
    A["Cell calls host.llm"] --> L["acquire _HOST_CALL_LOCK"]
    L --> S["send host_call"]
    S --> W["wait for host_response matching id"]
    W --> U["release lock"]
    U --> N["Cell continues"]
    R["worker respawn"] --> G["generation++"]
    G --> X["all old bash one-shot tokens fail"]

Acceptance thinking: if you allow concurrent host_call without a lock, what you save is latency; what you buy is occasional mis-bound results—unacceptable in a research scene.

Lab D · provenance binds to generation

Wrong implementation: capture_environment() freezes the daemon’s pip freeze. Correct implementation: look up “the generation_id of the language slot that wrote this Artifact” and freeze that interpreter’s package set; if unreadable, record the missing reason.

Product copy: writing “environment unknown (reason)” in the UI is far better than writing “environment = a list of packages that do not belong to it.”

Definition trade-offs (this step’s dedicated table)

How it couples to previous and later modules

• Steps 5–6 Host’s soft-fail contract depends on this step turning {"error"} into an in-Cell exception.
• Step 14 Artifact depends on this step’s generation fingerprint.
• Step 19 sandbox stacks outside spawn; it cannot replace the protocol split.

✅ This step’s acceptance: you can explain “why R uses fd3/fd4”; you can explain “why the frame cap is 12”; you can explain “why an R artifact must not be stamped with a Python freeze.” If you cannot, you have not yet understood the kernel.

Purpose

The ledger precedes the UI: tool declarations and results, Cell attempts, terminal facts, usage, approval resolutions must all be reconstructable. After a daemon restart, you cannot rely on “what the browser still remembers.”

Implementation shape

• store.py: single connection, RLock, schema/migrations, read-only query guardrails, compatibility façade
• storage/: frame / artifact / action ledger / approvals / settings / memories… repositories
• agent/ledger.py: write AgentEvent as immutable group/event; a reducer fills in half-open tool groups after a crash

Key invariants:

• A native assistant declaration + all of its tool results is an atomic group (compaction cannot split it either)
• Terminal state is appended; it is not reverse-inferred from chat bubbles
• host.query is read-only and denylists settings/permissions/ledger and other sensitive tables
• PRAGMA user_version + schema_migrations; migrations in a single transaction, not WAL (an audit-store choice)

Stack

• stdlib sqlite3
• Explicit migration map Store._migrate

Definition trade-offs

Strengths and costs

• Strength: Timeline, cost, and compliance audit share one source; tests can assert the trace.
• Cost: you must maintain both the projection (messages) and the truth (ledger); it is mentally expensive.

How it couples to previous and later modules

• Engine events → Ledger writer; Gateway projects assistant-visible text; restore reads the journal.

flowchart TB
    E["AgentEvent"] --> W["RuntimeActionLedger"]
    W --> G["action_groups"]
    W --> V["action_events"]
    G --> R["reducer → provider-safe history"]
    R --> M["next model.complete"]
    UI["chat bubbles"] -.->|projection only| G

8.4 Migration discipline (copy into team convention)

• New version = new step function + SCHEMA_VERSION += 1
• A step must not commit itself; the outer layer is a single transaction
• integrity_check first, then backup API, then migrate; on failure keep the backup
• Backfills must be WHERE-idempotent
• Do not casually change journal_mode/synchronous: this is an audit store, not a high-QPS business store

8.5 host.query denylist mental model

The Agent can “look at its own database”—that is powerful and dangerous. The denylist at least covers: settings, permission tables, the raw ledger, recovery journal, credentials-related. Match after stripping literals so SELECT 'settings' is not a false positive, but the "settings" identifier is still blocked.

✅ This step’s acceptance: manufacture a crash fixture of “tool group missing results”; after restart the reducer fills a canonical error, rather than sending a half-open batch back to the model.

Purpose

Make deterministic orchestration a named Tool subclass catalog: schema, safety policy, and execute() in the same file; and close non-scientific turns with the Engine’s own finalize_response.

Implementation shape

• tools/base.py: Tool / ToolSpec / invoke() (forbid calling execute directly and bypassing the envelope)
• tools/registry.py: TOOL_TYPES the unique built-in instantiation point; forbid registering bash / submit_output
• agent/finalize.py: closed schema (summary/findings/metrics/artifacts/limitations/next_steps/completion_bullets)
• Scientific-library breadth does not inflate tool count: only science_list_dbs + science_search

Stack

• JSON Schema subset validation (in-house / built-in)
• provider adapters translate ToolSpec into each vendor’s wire

Definition trade-offs

Strengths and costs

• Strength: classification is clear; permission metadata and behavior do not drift.
• Cost: the catalog will grow; you need taxonomy/side_effect_class to keep it.

How it couples to previous and later modules

• route_action recognizes finalize; WebActionExecutor / CLI runtime execute the batch; results enter the Ledger.

flowchart LR
    SPEC["ToolSpec catalog"] --> LLM["provider tools params"]
    LLM --> CALLS["native tool_calls"]
    CALLS --> RA["route_action"]
    RA -->|batch| INV["Tool.invoke → Dispatcher"]
    RA -->|finalize| FIN["finalize.py validate → CompletionRecord"]

9.4 Control-tool parallel waves (do not copy this wrong when implementing)

A prefix that is read-only and whose resource_keys do not conflict can run in parallel; the first mutating/unknown call is a barrier, then serial; write-back to history must follow the provider’s original order. Parallel completion order must never scramble the canonical group—otherwise replay and compaction all break.

9.5 finalize_response minimal-schema mental model

The model must give:

• summary (grounded)
• completion_bullets (1–4 phrases of completed actions)
• optional findings/metrics/artifacts/limitations/next_steps

The Host then validates the same closed schema again. A scientific Cell must not close with it; keep using host.submit_output.

✅ This step’s acceptance: attempting register_tool(bash) fails; a sole finalize_response produces a structured completion; when other tools are mixed in, it does not walk FinalizeAction.

Purpose

Write domain knowledge (docking, single-cell, folding flows) as loadable recipes: SKILL.md + optional kernel.py sidecar. The model first sees name+summary; when needed it host.search_skills / load_skill—progressive disclosure.

Implementation shape

• Repo skills/<name>/SKILL.md
• openai4s/skills_loader/loader.py
• User skills only under <data_dir>/user-skills; on a bundled same-name conflict, bundled (read-only) wins
• sidecar compile-check before use
• Host authoring flow: draft → personal; Web Customize is user origin and cannot forge a trusted origin

Stack

• Markdown frontmatter + file tree
• Generation-bound to Store capability state (the loader does not cache a closed repo)

Definition trade-offs

Strengths and costs

• Strength: scientific flows are versionable and reviewable; the engine stays thin.
• Cost: recipe quality variance becomes product experience; you need a readiness check.

How it couples to previous and later modules

• Tools: search_skills / load_skill; in-Cell host.skills.*; remote compute skills carry provider.py (step 20).

flowchart TD
    CAT["catalog: name+summary"] --> M["model decides whether to load"]
    M -->|load| MD["SKILL.md full text"]
    M -->|sidecar| PY["kernel.py compile-check"]
    MD --> CELL["Cell executes by recipe"]
    PY --> CELL

10.4 Write your first Skill (minimal recipe)

skills/insulin-quicklook/
  SKILL.md

Suggested SKILL.md structure:

---
name: insulin-quicklook
summary: 从 UniProt 拉取 INS 摘要并在内核中计算序列长度
---

# Insulin quicklook

1. 用 science_search 查 UniProt: INS human
2. 将序列写入 workspace
3. 开一个 python cell 计算 len(seq) 并作图
4. host.save_artifact(...)
5. host.submit_output(...)

Do not write the recipe as a “mysterious JSON tool.” The recipe’s readers are the model and a human reviewer.

✅ This step’s acceptance: before load, the system prompt does not contain the full text; after load, a Cell can import the sidecar; a user skill cannot shadow the built-in catalog.

Purpose

Productize the engine into a local workbench: REST for resources, WS for turn streaming events. Stay zero-framework—one fewer dependency conflict in a scientist’s environment.

Implementation shape

• server/gateway.py: composition adapter (large, but a façade)
• WSHub: subscribe by root_frame_id, broadcast, disconnect resume cursor
• SessionRunner: session state, job queue, run_message, _loop
• server/webui/: index.html / app.js / style.css no build step, served as static files from the worktree
• Default bind 127.0.0.1; local auth / security headers (CSP etc.)

Stack

• http.server + hand-written WS handshake/frames (see ws_frames.py)
• Thread model: blocking POST runs a turn + WS push

Definition trade-offs

Strengths and costs

• Strength: ./start.sh is simple; JS changes take effect on refresh.
• Cost: the gateway file is huge; new routes must land in a focused service, not keep swelling it.

How it couples to previous and later modules

• The next chapter is dedicated to the send path; Artifact/permission/restore services hang on the same runner.

flowchart LR
    B["Browser"] -->|REST| G["gateway.py"]
    B -->|WS| H["WSHub"]
    G --> SR["SessionRunner"]
    SR --> ENG["AgentEngine"]
    SR --> H
    G --> STATIC["webui/*"]

✅ This step’s acceptance: after openai4s serve, GET / is 200; WS upgrade succeeds; a second instance is refused because of the pidfile.

Purpose

Open the full loop a user can perceive: input box → POST message → outer-loop multi-turn → WS events → assistant bubble / Activity / Artifact. This is the main path for accepting the product, and a preview of the tutorial’s most important sequence diagram.

Implementation shape (against source)

1. composer: send(text, opts) in server/webui/app.js
2. If there is no session: POST /frames creates one, and sub(frameId) subscribes to WS
3. Optimistically render the user bubble; if S.running then mark queued (server FIFO accepts)
4. sub(currentId) first, then POST—otherwise the first text_reset / text_chunk is dropped for lack of a subscriber
5. POST /frames/{id}/message (singular; wait:false) → Gateway returns 202 + {job_id, execution_id, request_id}; the turn runs on a background thread and does not block HTTP
6. SessionRunner.submit_message → FIFO ticket + MessageJob → run_message
7. SessionRunner._loop assembles AgentEngine + ChatModel + WebActionExecutor + CompactionPolicy + WebEventSink
8. During engine turns: TextDelta / tool / cell events → emit → WSHub.broadcast (each stamped with a monotonic seq)
9. The frontend stitches chunks into the assistant bubble; tools become Activity cards; file writes become Artifacts
10. Completion: server/completions.py projects structured output / bullets / artifact delta as the final assistant message, then sends a terminal frame_update; S.running=false, composer unlocks

WS resume contract (must be written into the product): connectWS() connects to /api/v1/ws; view_session carries since_seq (the largest seq this tab has applied) and epoch (daemon process identity). After a daemon restart epoch changes → replay_begin.gap=true → the UI must REST re-pull history; it must not pretend “you have caught up.” The buffer only covers the currently in-progress turn, not a full event log.

Stack

• fetch REST + WebSocket client
• Server-side threading + Event cancellation
• Hand-written WS: ws_frames.py; resume via seq + epoch, not Socket.IO

Definition trade-offs

Strengths and costs

• Strength: the “chat” the user understands is decoupled from the real ledger; refresh can re-pull messages; 202 makes Stop / queue UX possible.
• Cost: subscribe timing, admission, queue hints, epoch gaps are all detail minefields.

How it couples to previous and later modules

• Full module-level replay is at the 🎬 at the end of this document; permission-card and Artifact events insert on the same WS stream.

sequenceDiagram
    autonumber
    participant U as user
    participant UI as app.js composer
    participant REST as gateway POST
    participant SR as SessionRunner
    participant ENG as AgentEngine
    participant K as Kernel/Tools
    participant WS as WSHub
    participant B as assistant bubble

    U->>UI: type a prompt and send
    UI->>UI: optimistic user bubble; openTurnTicket
    UI->>WS: view_session(fid, since_seq, epoch)
    UI->>REST: POST /frames/{id}/message wait:false
    REST-->>UI: 202 execution_id
    REST->>SR: submit_message → FIFO → run_message
    SR->>WS: text_reset
    SR->>ENG: _loop → Engine.run
    loop each turn
      ENG->>ENG: model.complete (SSE deltas)
      ENG-->>WS: text_chunk / notebook_cell / activity seq++
      WS-->>B: stream render
      ENG->>K: Tool batch or Cell
      K-->>ENG: observation
    end
    ENG-->>SR: submitted / finalize / max_turns
    SR-->>WS: completions projection + frame_update terminal
    WS-->>B: completed state
    B-->>U: readable reply + Artifact entry

12.4 Four timing things the frontend must get right

1. Generate and remember the admission id before POST (comment/pin scenes); a server-issued id does not help after disconnect.
2. sub(frameId) before POST; the first-packet delta must not be dropped.
3. Use the S.running snapshot at dispatch time to decide whether to openTurnTicket—there is an await in the middle; an old snapshot expires.
4. Do not let the header model overwrite a session-pinned revision (the source comments record this pit).
5. Reconnect with since_seq + epoch; an epoch change must REST re-pull; do not blindly trust the buffer.

12.5 Server run_message responsibility list

• Validate frame/project scope
• Write the user message (including annotation consumption)
• If busy, enqueue; if idle, start a thread (wait:false path)
• Inside the thread: take a FIFO ticket → _loop → completions project the completion message → release the ticket → pull the next queued item
• Any exception: write a terminal failure (do not double-write for the same job)

✅ This step’s acceptance: run one sentence by hand in the browser; Network shows POST .../message returning 202; WS has text_reset/text_chunk; after refresh history is still there; sending again while running queues rather than disappearing; after killing the daemon and reconnecting, an epoch change triggers a history re-pull.

Purpose

A scientific Agent will write files, go to the network, run a shell. The product must turn risky actions into clickable approval cards, and: no browser subscriber ≠ auto-allow; headless defaults to deny.

Implementation shape

• permissions.py + permission rules/requests in the Store
• HostDispatcher asks before a risky tool
• WebUI renders the approval card; the resolution is written back to SQLite
• Semantics:
• Process still alive: wake the same blocked call
• Daemon already restarted: record permission_resolution (the old operation was not executed), require Continue/replan
• once: exact match of conversation/tool/target within 15 minutes, atomic consume
• OPENAI4S_UNATTENDED_APPROVAL=deny|allow

Stack

• Persistent request rows + condition-variable/event wake
• Frontend WS event permission_request

Definition trade-offs

Strengths and costs

• Strength: a security narrative a lab can accept; audit is complete.
• Cost: after restart, “clicked allow but it did not execute” needs UI copy to educate, or users think it is a bug.

How it couples to previous and later modules

• Tool classes declare a permission target; the bash capability is bound to generation at another layer.

sequenceDiagram
    participant T as Tool/host call
    participant D as Dispatcher
    participant DB as SQLite
    participant UI as approval card
    T->>D: risky action
    D->>DB: write permission_request
    D-->>UI: WS push card
    UI->>DB: allow once/session/...
    alt daemon not restarted
      DB-->>D: wake the original call
      D-->>T: continue execute
    else daemon already restarted
      DB-->>UI: requires_continue
      UI->>T: user explicitly Continue/replan
    end

✅ This step’s acceptance: under headless deny, a risky tool fails; with a UI the card is clickable; after restart, once does not re-ignite old args.

Purpose

What a scientist wants is not “the model said it drew a figure,” but a versioned object on disk: previewable, roll-backable, able to say “produced by which Cell / which environment / which inputs.”

Implementation shape

• server/artifacts.py: ArtifactManager (capture, versions, CAS)
• End of a Cell transaction: savefig, workspace diff → a new version
• host.save_artifact / native SaveArtifactTool
• provenance: bind to the kernel generation’s runtime/interpreter/env_name/generation_id
• In-kernel kernel/provenance.py: object-level lineage tags (can OPENAI4S_PROVENANCE_OFF=1)
• Retrieval results carry a provenance envelope (DB, request, time, SHA-256)

Stack

• Content-addressed files + SQLite metadata
• matplotlib figures: gateway is responsible for savefig (do not autoclose in the worker)

Definition trade-offs

Strengths and costs

• Strength: a reproducible narrative; the UI can do “produced by cell N.”
• Cost: large files and version explosion need quotas and a cleanup policy (later).

How it couples to previous and later modules

• finalize/submit can cite artifact ids; an exported package carries versions and provenance.

flowchart TB
    CELL["Cell writes files / savefig"] --> CAP["ArtifactManager.capture"]
    CAP --> V["artifact_version"]
    GEN["kernel generation"] --> V
    LIN["lineage_edges"] --> V
    V --> UI["Artifact panel"]
    V --> EXP["session package"]

✅ This step’s acceptance: an R Cell artifact’s provenance must not display as a Python freeze; two edits of the same path produce two version_ids.

Purpose

A long scientific session will blow the context. Compaction must keep reproducible clues, and must not split a native-tool atomic group or a code/observation pair.

Implementation shape

• agent/compaction.py: estimate_tokens / should_compact / compact / CompactionPolicy
• Large outputs land as a content-addressed archive; the message keeps a preview + SHA-256
• Structured handoff fields: Objective / Constraints / Decisions / Done / In Progress / Blocked / Next Move / Key Artifacts / Active Kernel Generation
• System prompt and standing context (skills/memory) are rebuilt every turn, not mistakenly wounded by compaction as “the conversation is too long”

Stack

• Pure-function module + optional LLM summary (SUMMARY_FORK)
• No hard Store dependency (metadata is injected by the caller)

Definition trade-offs

Strengths and costs

• Strength: long sessions can still continue; cost is controllable.
• Cost: summary quality depends on the model; you must test “after compaction it still knows the current generation.”

How it couples to previous and later modules

• AgentEngine every turn context_policy.prepare; Web passes in branch/ledger metadata.

flowchart LR
    M["messages"] --> E["ContextEstimate"]
    E -->|over threshold| C["compact"]
    C --> S["structured handoff"]
    C --> A["disk archive sha256"]
    S --> M2["short history prepared for the model"]

✅ This step’s acceptance: construct an oversized tool result; after compaction a preview+hash appears, and the tool group is not split into an illegal state.

Purpose

The main Agent fans subtasks out to child Agents in parallel (literature one group, cleaning another), but there must be budgets and a depth leaf, or it fractally explodes the machine.

Implementation shape

• agent/delegation.py: tree, budget, cancel, steer
• Caps: FANOUT_CAP=48, SESSION_CAP=1000, MAX_DEPTH=4 (layer 4 cannot delegate further)
• host.delegate / collect / stop_child / send_message
• Cancel is precise to a subtree; a stopped child cannot publish late output
• Gateway hangs a shared DelegationBudget on SessionState

Stack

• ThreadPoolExecutor + contextvars to pass the tree
• Child Agents reuse the same AgentEngine loop

Definition trade-offs

Strengths and costs

• Strength: real parallel scientific split.
• Cost: resource and permission propagation is complex; a child Agent’s workspace/policy must be explicit.

How it couples to previous and later modules

• Host DelegationService; UI composer has a delegation option; Ledger records child runs.

flowchart TB
    R["Root Agent"] -->|delegate| C1["Child ≤ depth 4"]
    R --> C2["Child"]
    C1 -->|depth<4| G["Grandchild"]
    C1 -->|depth=4| L["Leaf cannot delegate further"]
    R -->|collect| OUT["aggregated results"]

✅ This step’s acceptance: delegate at depth 4 fails; after stop_child there is no late submit_output; exceeding session spawn errors.

Purpose

In the same session, Agent turns, user REPL, environment switches, and restore writers must not race for the kernel. You need a FIFO of exact owner + lease, not “fire SIGINT at the session PID at random.”

Implementation shape

• execution/: coordinator and watchdog (CLI also uses it, so it does not live in server/)
• server/execution_coordinator.py: Web adapter
• kernel/supervisor.py: Python/R slot lifecycle; never reads protocol frames
• Interrupt must carry execution_id + owner.kind + owner.id + frozen lease
• Environment switch is build-first: only cut the pointer when the new worker is ready

Stack

• Queue tickets + condition variables
• generation UUID against ABA

Definition trade-offs

Strengths and costs

• Strength: restore and concurrency are testable; avoid “killing the wrong generation of process.”
• Cost: many concepts (ticket/lease/generation); docs must be clear.

How it couples to previous and later modules

• run_message, cell_run, recovery all come to take a ticket; Artifact capture hangs inside the ticket lifecycle.

flowchart LR
    Q["Agent / REPL / lifecycle / recovery"] --> FIFO["ExecutionCoordinator"]
    FIFO --> OWN["exact owner + lease"]
    OWN --> K["Kernel.execute"]
    STOP["Stop"] --> OWN

✅ This step’s acceptance: while a turn is running, a second message queues; Stop only interrupts the current ticket; a simulated old watchdog cannot kill the new generation.

Purpose

Turn UniProt/RCSB/ChEMBL/PubChem/arXiv/OpenAlex etc. into two tools + host.science.*, and force provenance so results become evidence rather than “model memory.”

Implementation shape

• tools/science.py + host science service
• Fixed HTTPS endpoints walk the network switch, SSRF/redirect guards, egress, approval, untrusted-output screening
• evidence.py / session package export
• workflows/ + openai4s/benchmark/: scientific-workflow benchmarks on a real Store/kernel (LLM/network injectable)

Stack

• stdlib HTTP client wrapper (via Host)
• JSON canonicalization version numbers

Definition trade-offs

Strengths and costs

• Strength: the tool table is stable; evidence is re-checkable.
• Cost: upstream API changes require maintaining normalization; rate limits need a degrade path.

How it couples to previous and later modules

• The main path of the first user story; Artifact source=provenance; shares the security layer.

flowchart LR
    Q["science_search"] --> C["connector normalize"]
    C --> P["provenance envelope"]
    P --> A["save_artifact(source=P)"]
    A --> E["evidence / export"]

✅ This step’s acceptance: after a mock upstream return, the artifact version contains sha256 and timestamp; changing the bytes changes the hash.

Purpose

A single sandbox cannot save a scientific Agent. You must stack mutually independent layers: OS sandbox, env allowlist, pre-exec classifier, dlopen hook, biosecurity, injection annotation, egress, session keys, CSP…

Implementation shape (layer table)

Stack

• Platform branches (darwin/linux); self-test probes
• Static/heuristic/optional LLM classification

Definition trade-offs

Strengths and costs

• Strength: one layer failing still leaves others; the compliance narrative is complete.
• Cost: many knobs; CI must run the Linux branch.

How it couples to previous and later modules

• Runs through Kernel spawn, Host network tools, and post-packaging smoke.

flowchart TB
    CELL["Agent Cell"] --> CL["pre-exec classifier"]
    CL --> SB["OS sandbox"]
    SB --> ENV["allowlisted env"]
    ENV --> RUN["worker"]
    RUN --> RPC["host RPC"]
    RPC --> EG["egress + permission"]
    RPC --> INJ["injection annotate"]

19.4 The correct way to expose locally

When a colleague needs access:

• ✅ SSH tunnel to 127.0.0.1:8760
• ✅ An explicit local auth / token latch (if you added one)
• ❌ Bare 0.0.0.0 on an untrusted network
• ❌ Treat the daemon as a multi-tenant gateway

docs/security.md opens with: read first, then expose. Copy that sentence into your README.

19.5 Biosecurity and injection are product features, not compliance stickers

Bioinformatics users will hit dual-use content. Trace screening is on by default; web-tool results must be annotated “data is not an instruction.” Turning them off requires an explicit env, and doctor must show the posture.

✅ This step’s acceptance: when sandbox self-test fails, auto reports degraded; enforce does not start a worker; web_fetch by default refuses link-local.

Purpose

When a local laptop cannot run AlphaFold / large-model inference, send a job to the user’s own GPU (SSH or NIM), while keeping the key and sandbox boundary.

Implementation shape

• openai4s/compute/: host-side manager/registry
• openai4s_compute_provider/: remote-side stdlib worker SDK
• Skills: skills/remote-compute-<id>/ (provider.json + provider.py)
• host.compute.* / host.fold (strictly no forgery)
• Two-stage secret erase: entry scrub_secret_env → after loading the provider, erase again by prefix
• The remote helper wraps another layer of confinement (home directory unreadable etc.); network is not isolated (it has to call APIs)

Stack

• SSH / docker CLI transport (not a generic pluggable Transport layer)
• Modal/SLURM not first-class yet (you can hand-write sbatch over SSH)

Definition trade-offs

Strengths and costs

• Strength: BYOC fits lab assets; the core stays thin.
• Cost: Prototype experience is sharp; docs must write the trust boundary clearly.

How it couples to previous and later modules

• Built after a stable Host/approval/Artifact; packaging can skip bundling the GPU stack at first.

sequenceDiagram
    participant A as Agent
    participant H as Host compute
    participant R as Remote provider SDK
    participant G as GPU node
    A->>H: compute.create/submit_job
    H->>H: approval + scrub
    H->>R: stage + confined helper
    R->>G: run
    G-->>R: out.tar.gz
    R-->>H: harvest
    H-->>A: artifact paths

✅ This step’s acceptance: without credentials, fold fails and does not fabricate; the helper exits on confinement self-test failure and does not read credentials.

Purpose

Let scientists who will not git clone still use it: Apple Silicon dmg, Linux tarball, Windows zip→WSL2, and pip install openai4s.

Implementation shape

• pyproject.toml publishes a wheel; skills*/envs*/workflows* must enter package data
• scripts/ release pipeline, DMG build, verify_release_artifacts.py
• macOS app: embedded Python + default scientific stack; ad-hoc signature, needs Gatekeeper guidance
• Windows: the launcher installs into WSL2 and runs the same Linux build; native Windows refuses to start a kernel
• openai4s doctor / diagnostics / verify-package

Stack

• uv / pip; platform scripts; optional micromamba kernel environment

Definition trade-offs

Strengths and costs

• Strength: distribution covers mainstream lab machines.
• Cost: three-platform release is expensive; notarization/signing is a continuing burden.

How it couples to previous and later modules

• All runtime invariants first; missing workflows in the package would make the benchmark fake-green—CI must block it.

flowchart TB
    SRC["source + skills/envs/workflows"] --> WHEEL["pip wheel"]
    SRC --> DMG["macOS arm64 dmg"]
    SRC --> TGZ["linux x86_64 tar.gz"]
    SRC --> ZIP["windows zip → WSL2"]
    WHEEL --> V["verify_release_artifacts"]
    DMG --> V
    TGZ --> V

✅ This step’s acceptance: after uv build, the wheel contains skills and workflows; on a clean machine after pip install, openai4s serve can start.

Module-touch list (read against this)

sequenceDiagram
    autonumber
    participant U as user
    participant UI as app.js
    participant GW as gateway.py
    participant SR as SessionRunner
    participant FIFO as ExecutionCoordinator
    participant ENG as AgentEngine
    participant LLM as llm.chat urllib
    participant RA as route_action
    participant HD as HostDispatcher
    participant PERM as permissions+SQLite
    participant K as Kernel worker
    participant SDK as sdk/host
    participant ART as ArtifactManager
    participant LED as ActionLedger
    participant WS as WSHub
    participant STORE as Store SQLite

    U->>UI: type prompt, enter
    UI->>UI: optimistic user bubble; clear composer
    alt no currentId
      UI->>GW: POST /frames
      GW->>SR: create SessionState + workspace
      GW->>STORE: persist frame
      GW-->>UI: {id}
      UI->>WS: sub(id)
    end
    UI->>WS: sub(currentId) force subscribe before sending
    UI->>GW: POST /frames/{id}/message wait:false
    GW->>STORE: append user message
    GW->>SR: run_message(...)
    SR->>FIFO: request ticket (queue if busy)
    FIFO-->>SR: obtain owner+lease
    SR->>ENG: _loop assemble ports then Engine.run

    Note over ENG,LLM: Turn 1 · control-plane retrieval
    ENG->>ENG: CompactionPolicy.prepare
    ENG->>LLM: complete(messages, tools, on_delta)
    LLM-->>WS: text deltas (via WebEventSink)
    WS-->>UI: text_chunk → assistant bubble streams in
    LLM-->>ENG: ModelReply(tool_calls=[science_search...])
    ENG->>RA: route_action → NativeToolBatch
    ENG->>LED: open tool action group
    ENG->>HD: Tool.invoke → science_search
    alt needs approval
      HD->>PERM: permission_request
      PERM-->>UI: approval card
      U->>UI: Allow once
      UI->>PERM: resolve
      PERM-->>HD: continue
    end
    HD-->>ENG: normalized result + provenance
    ENG->>LED: append tool results (atomic group)
    ENG->>STORE: usage / frames tokens
    Note over ENG: observation written back to messages, turn+=1

    Note over ENG,K: Turn 2 · scientific-plane Cell
    ENG->>LLM: complete(...)
    LLM-->>UI: optional short explanation text
    LLM-->>ENG: ModelReply(content contains ```python)
    ENG->>RA: route_action → CodeCell(python)
    ENG->>LED: cell attempt group
    ENG->>K: if no worker then lazy spawn + sandbox
    K->>K: run analysis code, matplotlib plot
    K->>SDK: host.save_artifact(...)
    SDK->>HD: host_call save_artifact
    HD->>ART: register version
    ART-->>WS: artifact event
    WS-->>UI: Artifact panel appears
    K->>SDK: host.submit_output(output, bullets)
    SDK->>HD: completion
    HD-->>ENG: CompletionPort set
    ENG->>LED: terminal submitted
    ENG-->>SR: EngineResult(stop_reason=submitted)

    SR->>STORE: project final assistant message (Chinese summary+bullets+artifact delta)
    SR-->>WS: terminal / done-class events
    WS-->>UI: bubble freezes; Stop hides; composer unlocks
    UI-->>U: readable conclusion + clickable figure and versions

    Note over FIFO: release ticket; if a queued message exists, next run_message

On this chain, where is the code you write?

Reasoning can be rented; the scientific runtime must be yours.

If the model chooses “tools-only then finalize”

The path at Turn 2 becomes: FinalizeAction → agent/finalize.py validate → no kernel start → still through Ledger and message projection back to the bubble. That is the meaning of the dual plane: not everything enters the kernel.

If the user sends another sentence while it is running

send() sees S.running: the bubble is marked queued → the same POST messages is accepted by FIFO → after the current ticket ends, the next turn opens automatically. The old “return directly and drop the message” is a product-level accident; you cannot go back.

B.13 Frame cap guessed as ASCII

Symptom: with lots of Chinese/emoji, the Notebook loses the traceback. Root: character cap × a wrong bytes-per-character assumption. Fix: derive from worst-case UTF-8/JSON escape (see worker.py comments); add a regression test.

B.14 autoclose matplotlib in the worker

Symptom: “the figure clearly showed but the Artifact does not have it.” Root: gateway has not savefig’d yet; the worker closed the figure first. Fix: capture responsibility is on the gateway; the worker must not close on its own.

B.15 Use the daemon’s pip freeze as an R artifact’s environment

Symptom: the provenance panel looks complete; paper reproduction does not match. Root: wrong provenance is worse than none. Fix: bind to the kernel generation that wrote the file; otherwise record missing explicitly.