Server

中文说明

The Web application lives here. This package wires the provider-neutral agent engine, the persistent Python and R kernels, the Host capability boundary, and the SQLite repositories into one HTTP/WebSocket server built out of nothing but the standard library. Domain logic belongs in the focused services in this directory; gateway.py is the compatibility and transport facade they are composed through.

Where this fits

browser
  |  REST requests + WebSocket events
  v
gateway.py
  |-- session-domain services and read projections
  |-- AgentEngine adapter (agent_run.py)
  |-- FIFO execution ownership (execution_coordinator.py)
  `-- lazy, session-owned Python and R kernel slots
         |
         `-- HostDispatcher -> permissions, tools, artifacts, data and delegation

• Gateway composition. gateway.py builds the stdlib ThreadingHTTPServer and wires everything into it: routing, REST handlers, WebSocket framing and resume, session runners, the services, storage, and static assets. A new algorithm normally belongs in a focused module rather than in the facade.
• REST and WebSocket. REST does the bounded request/response work and serves the session-domain read models. The WebSocket channel carries the live stream: agent prose, action and cell lifecycle, approvals, Notebook updates, and terminal events, buffered so that a reconnecting browser can resume.
• Session services and projections. The mutation services own plans, reviews, artifacts, branching, recovery, packages, Skills, and deletion. The projection services turn canonical ledger, execution, lineage, context, and security state into redacted DTOs a browser can safely hold. A projection is a view; it is never the underlying terminal or transactional signal.
• Kernel ownership. A Web session owns an independent lazy Python slot and R slot through its SessionRunner. execution_coordinator.py hands out FIFO tickets so the Agent, the user REPL, recovery, and lifecycle writers never run over each other, and an interrupt reaches only the exact owner holding the exact lease. Tool-only routing does not start the foreground session slot, though an individual tool may manage a dedicated worker of its own.
• Persistence boundary. Durable facts are written through Store repositories. WebSocket state and live kernel namespaces are process-local. No transaction spans SQLite, workspace files, a kernel process, and a socket delivery.

The versioned surface

• One prefix, and no legacy alias. Everything reachable lives under /api/v1, and API_ROOT is defined once in contract.py because two very different callers need it: the gateway routes on it and the CLI builds daemon URLs from it. They drifted — openai4s share hard-coded /api/, so every one of its subcommands 404'd against the daemon's own refusal. An un-versioned /api/... now gets that refusal explicitly rather than falling through to the SPA shell, which would have answered 200 with HTML.
• A credential is required, not optional. The daemon executes code, so it does not answer without a token even on loopback; /health and /api/v1/auth/status are the only exceptions, and the second exists because a client cannot be told it needs a token by a response it is not allowed to read. A ?token= may be traded for a cookie on the root page only — an allowlist, because the older subtractive rule made /preview/<id>?token=… a link that set a durable cookie and handed over the file.
• One failure envelope. A failure carries the human error message it always had, plus a stable machine code and the request_id that ties it to the structured log; the enrichment is additive, so a client reading error is unaffected. A GatewayError's prose passes through untouched, because the 409/413/429 refusals carry the text a user needs in order to act. An arbitrary exception is projected at the boundary rather than filtered inside the envelope: a filter would have to guess which messages are safe, and it guesses wrong in the direction that destroys the good ones.
• Reads are paged, and events are numbered. The session list is a keyset page — an opaque cursor (parse it and you are coupled to the sort key), a has_more that is observed rather than inferred, and a 400 on a cursor that cannot be read rather than a silent restart from page one. WebSocket events carry a monotonic per-session seq; a reconnecting client resumes from its cursor inside replay_begin/replay_end, and a cursor that cannot be placed in this daemon's stream — a different epoch, or none at all — is declared a gap instead of being trusted.
• A turn is identified by its execution. Frames outlive turns and two turns overlap, and a client may legitimately reuse X-Request-Id, so execution_id is what rides processing, both terminal events, and the resume window. One request also produces exactly one authoritative failure: the inner and outer handlers hand off by job id, so a fault while finalizing cannot append a second terminal row that contradicts the first.
• An admission is a durable record, not a hope. A pinned comment is claimed for exactly one turn, and the reservation id is minted by the client before it sends — a server-minted id is unknown to a browser whose 202 was lost, which leaves nothing to ask about. GET /api/v1/frames/{id}/admissions/{reservation} says what became of it, so a client that lost the answer neither resends (double work) nor abandons the comments (silent loss). The state is derived from the pins, which are what a turn actually consumed; the ledger supplies correlation only. Anything still reserved at boot was stranded by a crash and is released.

Completion, Notebook, and recovery boundaries

• A Cell result comes back to the outer loop as an observation; on its own it does not complete the task. Completion requires either a sole valid Engine-owned finalize_response or a host.submit_output(...) from inside a Python Cell. An R Cell cannot complete a task at all.
• With Stage 1 trusted delivery enabled, completion links are built by one URL helper from exact immutable version ids. The snapshot scope, size, and checksum are verified first; then the final assistant message and delivery manifest commit together before the link-bearing text_chunk is emitted with its stable delivery_id. If that socket publication is lost, the committed message is still recovered through the ordinary REST reopen path; the committed row and stable id are also explicit inputs for a future or operator-driven replay, but the Stage 1 ledger does not drive re-emission. The ordinary bounded WS sequence buffer may replay it while the turn remains live; terminal/restart recovery uses REST. A failed verification or audit publishes no success link.
• Re-capturing the current head's bytes reuses the version and appends a scoped capture observation for the new producing Cell and lineage. The original version's producer/provenance remains immutable. Stage 1 observations are local-only; Session package, share, and export do not yet serialize them.
• Stage 1 standard-profile admission is local and side-effect free. Ordinary turns remain routable for native tools and structured finalization; a routed Code Cell is refused before pending-environment application, identity, attempt, safety or runtime. Direct Cells share the same boundary, while approved/resumed scientific plans retain a pre-status-transition check. The UI keeps persistent banners and a copy-only managed repair card. A repair builds and verifies fresh Python/R generations before moving their pointers.
• A Cell whose only content is the host.submit_output protocol call still runs, and it stays in the raw execution and audit history, but the live and reopened Notebook projections filter it out. The .ipynb exporter reads immutable execution history without that filter, so its output is a raw/audit export and may include that system Cell.
• Recovery execution is wired through REST/UI, FIFO ownership, and the Python/R candidate pipelines, but it remains Partial: unsafe or nondeterministic Cells are classified never, no attempt is made to serialize an arbitrary historical namespace, and a language candidate that cannot become active can stop the overall recovery with an explicit Partial result.

Files

Subdirectories

Change guidance

• Keep gateway.py a composition and compatibility facade, edited surgically. New domain behaviour goes into the service that owns it.
• Any change to kernel lifecycle, WebSocket streaming, execution ownership, or artifact capture needs an end-to-end browser run on top of the focused tests.
• Browser DTOs stay bounded and redacted. Raw provider payloads, tool arguments, credentials, and unrestricted filesystem paths do not belong in a projection.

See the repository architecture guide, Web application guide, and the webui/ README.