From 9430c499ec7b7795d70bda18f07e172a7a266a9e Mon Sep 17 00:00:00 2001 From: dajiaohuang Date: Sat, 29 Aug 2026 22:35:34 +0800 Subject: [PATCH] docs: document hosted reliability boundaries --- README.md | 157 ++++++++++++++++++++++++------------- src/pages/developers.astro | 23 +++++- src/pages/start.astro | 10 ++- 3 files changed, 130 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index e65014a..0b96f68 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,25 @@ # SagaSmithAI Website -[Live site](https://sagasmithai.github.io) · [Platform overview](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [Local Agent Kit](https://github.com/SagaSmithAI/SagaSmith-agent) +[Live site](https://sagasmithai.github.io) · [Get started](https://sagasmithai.github.io/start) · [Developer map](https://sagasmithai.github.io/developers) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [Local Agent Kit](https://github.com/SagaSmithAI/SagaSmith-agent) -The bilingual static organization site for SagaSmithAI, an AI-native TTRPG platform. It is a public product and developer entry surface, not a runtime dashboard, hosted campaign service, or replacement for component documentation. +This repository builds the bilingual static organization site for SagaSmithAI, an AI-native TTRPG platform. The site is a public product and developer entry point. It is not a runtime dashboard, a hosted campaign service, or a substitute for the versioned documentation in each component repository. -## Information architecture +## Choose a distribution -| Route | Purpose | -|---|---| -| `/` | Product thesis, Local/Hosted contract map, experience boundaries, maturity, and recent progress | -| `/start` | Current release-locked Local Kit install, MCP-host templates, transports, and SagaSmith Web development entry | -| `/developers` | Authoritative contract, ownership boundaries, and current repository topology | -| `/library` | Current Content Pack inventory and integrity/authority/rights boundaries | -| `/updates` | Dated public progress summaries with explicit evidence limits | -| `/security` | Private vulnerability-reporting routes and sensitive-data guidance | -| `/privacy` | Privacy notice for this static GitHub Pages site | -| `/404` | Bilingual not-found recovery page | +SagaSmith has two deployment shapes over the same authoritative domain contract: -Chinese is the default language. The language control reveals complete English copy on the same static routes and stores only `sagasmith-language` in browser `localStorage`. +| Distribution | Use it for | Host boundary | Storage boundary | +|---|---|---|---| +| [Local Agent Kit](https://github.com/SagaSmithAI/SagaSmith-agent) | Self-hosted Agents, bots, desktop tools, and local Workbenches | SagaSmith Agent or another MCP Host | Operator-controlled SQLite and local files | +| [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) | Accounts, collaborative rooms, hosted workers, Forge, Module Studio, and operations | Browser → API/BFF → Agent worker | PostgreSQL, Redis, private object storage, and isolated domain state | + +Local Kit does not depend on SagaSmith Web. Local and Hosted may use different transports, authentication, storage, and deployment, but they preserve the same handlers, tool schemas, structured errors, authority, revisions, idempotency, and rule-write semantics. ## Current repository map | Layer | Current repository | |---|---| -| Agent host and Local Agent Kit | [`SagaSmith-agent`](https://github.com/SagaSmithAI/SagaSmith-agent) | +| Agent host, Local Agent Kit, and Hosted worker base | [`SagaSmith-agent`](https://github.com/SagaSmithAI/SagaSmith-agent) | | Hosted browser product | [`SagaSmith-Web`](https://github.com/SagaSmithAI/SagaSmith-Web) | | System-neutral runtime | [`Sagasmith-core`](https://github.com/SagaSmithAI/Sagasmith-core) | | D&D Domain / MCP / Skills / UI | [`Sagasmith-dnd`](https://github.com/SagaSmithAI/Sagasmith-dnd) | @@ -32,34 +28,86 @@ Chinese is the default language. The language control reveals complete English c | Rights-aware Content Pack catalog | [`SagaSmith-dnd-content-library`](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library) | | Organization profile and community policy | [`.github`](https://github.com/SagaSmithAI/.github) | -Former standalone MCP, Skills, UI, and generic Module Generator repositories are archived read-only history. They are not current documentation, release inputs, producers, consumers, or compatibility fallbacks. - -## Product boundaries - -- SagaSmith Local Agent Kit and SagaSmith Web are two deployments of the - `sagasmith.authoritative-mcp/v2` application contract, with MCP `2026-07-28` as the modern - protocol target. -- Transport, authentication, storage, and deployment may differ. Handlers, tool schemas, errors, authority, revisions, idempotency, and rule-write semantics may not. -- Modern requests use `server/discover`, carry protocol/capability/identity metadata on every - request, and never treat initialize, a connection, or `Mcp-Session-Id` as authority. Domain - `tools/list` is deterministic and privately cacheable for one authorization scope; the Host - projects the task-relevant facade subset without mutating the server catalog. -- Cross-call state uses explicit server-issued opaque handles or explicit campaign/revision - parameters. Handles have an owner and expiry, are re-authorized on every call, and are names—not - bearer capabilities. Legacy initialize/session exposure is retained only by an explicitly pinned - compatibility adapter while older clients are migrated. -- SagaSmith Web owns accounts, sessions, quota, collaboration, Forge, Module Studio, hosted orchestration, and cloud projections. Domain MCPs remain authoritative for game state. -- Agent and Skills may interpret, facilitate, and propose. Domain runtimes and MCP settle deterministic rules and authoritative writes. -- `sagasmith.content-package` v2 Packs do not carry campaign permissions, ActorKnowledge, progress, random streams, branches, or snapshots. -- Public repository or catalog visibility is not a content license. Every Pack, source, image, map, font, and derived asset retains its own rights requirements. -- Extended ruleset import is Experimental and does not imply arbitrary unadapted rulebooks can execute safely. -- Local release profiles and SagaSmith Web production builds pin exact validated component commits. - Rollback restores the previous complete lock and compatible data/schema state; archived split - repositories are never release inputs or fallbacks. - -## Development and validation - -Requires Node.js 22.12+. +Former standalone MCP, Skills, UI, and generic Module Generator repositories are archived read-only history. They are not current installation paths, release inputs, producers, consumers, or compatibility fallbacks. Historical news may retain links that were accurate on its publication date. + +## MCP 2026-07-28 contract + +`sagasmith.authoritative-mcp/v2` uses MCP `2026-07-28` as its modern protocol target: + +- A modern Host calls `server/discover` and supplies protocol, capability, and trusted identity metadata on every request. It does not derive authority from initialization, a connection, or `Mcp-Session-Id`. +- Each domain exposes a deterministically sorted, authorization-scoped catalog. `tools/list` does not change because another request on the same connection mutated phase or exposure state. +- The Host connects only the MCP for the campaign's current `system_id`, then projects the relevant system/phase/role/task facade. SagaSmith Web persists no more than **16 sorted, unique tool IDs** with a turn. This is a Host selection policy, not an MCP protocol limit and never a replacement for call-time authorization. +- Cross-call state uses an explicit server-issued opaque handle or explicit campaign/revision parameters. A handle has an owner and expiry, is re-authorized on every request, and is a name rather than a bearer capability. +- HTTP validates authorization on every request. Connection pools never pool implicit principal/session state, and browser or provider tokens are never passed through to a domain MCP. +- The pinned legacy initialize/session adapter exists only for an atomic rollback of a compatible Web, Agent, Core, and domain set. Modern and legacy components must not be mixed. + +The Host keeps model-visible tool lists small because selection accuracy generally falls when many irrelevant low-level tools compete. Domain MCPs can retain a complete, stable catalog while the Host presents a compact set of facade/workflow tools for the current task. + +## Hosted reliability and trust boundaries + +SagaSmith Web owns hosted workflow; the matching domain MCP remains the sole authority for campaign membership, actor authority, phase/combat/random state, revision, idempotency, settlement, and Pack activation. + +### Durable room turns + +Every accepted room action persists the user message and a durable `RoomTurnJob`. Its states are `queued`, `running`, `waiting`, `succeeded`, `failed`, and `cancelled`. Leases, heartbeats, retry counts, error classification, result references, startup recovery, and periodic recovery allow work to survive worker or Web restarts. + +Browser, Web, Agent, and MCP retries reuse one business idempotency key. Quota reservations are renewed while work is live and settled or released from durable state. An optional `base_revision` enables optimistic concurrency without holding a room or database lock for the LLM turn; only the final ordered message/outbox settlement uses short per-room serialization. A stale revision is recoverable instead of silently overwriting newer state. + +If a domain operation commits but Web publication fails, the saved standard MCP result is reused. The write and quota charge are not repeated. + +### Identity and delegation + +Trusted authority context is structurally separate from player text. It identifies the caller/workload, requester/resource owner, acting Host/character, allowed operations, audience, campaign, `room_turn_id`, `base_revision`, and expiry. The model cannot choose authoritative identity. + +Web signs a short-lived delegation for the exact target MCP audience. D&D and CoC use their hosted Streamable HTTP paths; Narrative remains process-local stdio in the current Hosted lock. A shared HTTP client may reuse connections, but every request carries and validates its own authority. + +### Results, media, and projections + +Hosted workers preserve the standard MCP `CallToolResult`, including text, image, audio, resource, and embedded-resource content. Web stores the original result and projects accepted media internally through `sagasmith.host-media/v1` (`HostMediaEnvelope`) into private artifact/object IDs with audience checks, bounds, checksums, and idempotent keys. This supports room/group images and combat grids without inventing a replacement MCP wire protocol. + +Web never reads or writes a domain's authoritative database directly. Successful MCP receipts drive a durable outbox and revisioned, audience-safe Web projections. Cache keys include authority revision; successful commits invalidate only affected scopes, while failed, rolled-back, and no-op operations do not invalidate data. Tool-catalog caching changes with authorization/catalog scope, not with each combat write. + +### MCP Tasks and Host jobs + +`RoomTurnJob` represents an entire Web-hosted LLM turn and is not an MCP Task. The negotiated `io.modelcontextprotocol/tasks` extension is used only for a genuinely long domain tool. Ordinary tools remain synchronous; claim, authenticated poll, cancel, timeout, and recovery activate only after capability negotiation and an accepted Task claim. The current reviewed path uses this for D&D module-draft work. + +### Worker workspaces + +Hosted workers use a stable opaque `--workspace-id` under the registered managed root. The supervisor bounds worker count and spawn concurrency, coalesces simultaneous starts, and applies TTL, LRU, count, and byte limits. Terminal success removes registered state and startup recovers crash-left markers. Unknown, malformed, external, legacy, symlinked, or active directories are retained for operator review rather than deleted. + +## Release lock, upgrade, and rollback + +The current Hosted manifest is [`component-versions.json`](https://github.com/SagaSmithAI/SagaSmith-Web/blob/main/component-versions.json), schema `sagasmith.release-lock/v3`. It records the exact reviewed Agent, Core, D&D, CoC, and Narrative revisions, protocol/auth contracts, runtime locks, and the maximum 16-tool Host projection. Its current status is a compatibility lock, not a published release. + +Local release profiles use the equivalent immutable lock in [`SagaSmith-agent`](https://github.com/SagaSmithAI/SagaSmith-agent/tree/main/sagasmith-release). Production upgrades move Web, Agent, Core, and the three domain components as one validated set after protocol and data canaries. Rollback restores the previous complete lock and compatible schema; it never substitutes an archived repository, an unlocked `main`, or hidden legacy session state. + +For operational commands and migration ordering, use the component-owned guides: + +- [SagaSmith Web deployment and recovery](https://github.com/SagaSmithAI/SagaSmith-Web/blob/main/docs/operations.md) +- [SagaSmith Web acceptance matrix](https://github.com/SagaSmithAI/SagaSmith-Web/blob/main/docs/test-matrix.md) +- [Local Agent Kit deployment](https://github.com/SagaSmithAI/SagaSmith-agent/blob/main/docs/deployment.md) +- [Local Agent Kit architecture](https://github.com/SagaSmithAI/SagaSmith-agent/blob/main/docs/architecture.md) + +Do not copy example secrets into production, use real campaign data in tests, or treat this static site's `main` branch as a product component lock. + +## Site information architecture + +| Route | Purpose | +|---|---| +| `/` | Product thesis, Local/Hosted contract map, experience boundaries, maturity, and recent progress | +| `/start` | Current release-locked Local Kit install, MCP-host templates, transports, and SagaSmith Web development entry | +| `/developers` | Authoritative contract, Hosted reliability boundaries, ownership, and current repository topology | +| `/library` | Content Pack inventory and integrity/authority/rights boundaries | +| `/updates` | Dated public progress summaries with explicit evidence limits | +| `/security` | Private vulnerability-reporting routes and sensitive-data guidance | +| `/privacy` | Privacy notice for this static GitHub Pages site | +| `/404` | Bilingual not-found recovery page | + +Chinese is the default language. The language control reveals complete English copy on the same static routes and stores only `sagasmith-language` in browser `localStorage`. + +## Develop and validate the site + +Node.js 22.12+ is required. ```bash npm ci @@ -69,32 +117,33 @@ npm run check:site npm run check:external ``` -`npm run check` runs the deterministic content/topology checks, production build, and built-site metadata/internal-link/asset-budget checks. `check:external` performs the network-dependent external-link pass separately. +`npm run check` runs deterministic content/topology checks, the production build, and built-site metadata/internal-link/asset-budget checks. `check:external` is the separate network-dependent external-link pass. -The GitHub Pages workflow builds only this repository and publishes `dist/`. It has no cross-repository release input or bundled Workbench. Pull requests run the same deterministic checks; deployment occurs only from `main` or an explicit workflow dispatch. +The GitHub Pages workflow builds only this repository and publishes `dist/`. Pull requests run deterministic checks; deployment occurs only from `main` or an explicit workflow dispatch. Domain Workbenches and other repositories are never bundled into the site artifact. -## Assets and visual source +## Observability and security scope -- `public/logo-wordmark.png`, `public/logo-mark.png`, and the original favicon path are first-party brand assets already committed to this Apache-2.0 website in PR #9. They remain covered by this repository's `LICENSE` and `NOTICE`. -- `public/og.png` is rendered at 1200×630 from the site-owned, reviewable `src/assets/og-source.svg`; it uses only inline vectors, text, and the documented site tokens. -- `public/favicon.svg` is a site-owned vector mark adapted from the existing website favicon and recolored to the current product palette. `public/icon-512.png` is rendered from the reviewable `src/assets/icon-source.svg` for exact manifest and Apple touch dimensions. -- The visual token names and interaction patterns are aligned with the current SagaSmith Web product language: void `#0c0d0d`, forge panel `#151716`, iron line `#2a2d2b`, vellum ink `#eee9dc`, forge gold `#d9ad5b`, and moss state `#718d6a`. -- SagaSmith Web is proprietary. No SagaSmith Web source file, texture, icon, private implementation, model, cache, or generated workflow is copied into this static repository. -- The site loads no remote font, analytics, image CDN, or third-party visual asset at runtime. +This static site has no account login, campaign data, hosted worker, analytics script, remote font, image CDN, or SagaSmithAI form backend. The language preference is local-only. GitHub Pages and linked destinations apply their own privacy policies. -## Main sources +Product telemetry belongs to the owning component. SagaSmith Web exposes low-cardinality service, MCP-phase, projection, durable-job, quota, database, outbox, and realtime metrics; user, campaign, room, job, and tool arguments are not metric labels. `traceparent`, `tracestate`, and `baggage` propagate through Web, Agent, and MCP boundaries. + +Never publish vulnerability details, credentials, private campaigns, personal data, provider responses, or restricted Pack/source content in a public issue. Use the [security route](https://sagasmithai.github.io/security) to find the private reporting path owned by the affected repository. + +## Source layout and assets ```text src/layouts/SiteLayout.astro Shared metadata, bilingual navigation, accessibility, and footer src/lib/site.ts Current repository, system-status, and Local profile data src/lib/news.ts Local dated-news loader -src/pages/ Every public route, including privacy, security, updates, and 404 +src/pages/ Public routes, including privacy, security, updates, and 404 src/styles/site.css Shared responsive visual system and reduced-motion handling news/ Dated historical progress sources scripts/ Content, built-site, and external-link checks public/ First-party brand assets, manifest, sitemap, and robots policy ``` +The committed wordmark, mark, favicon, manifest icon, and SVG render sources are first-party site assets covered by this repository's Apache-2.0 license and `NOTICE`. The site copies no proprietary SagaSmith Web source, texture, icon, model, cache, or generated workflow. + ## License Apache-2.0. See [`NOTICE`](NOTICE). Repository visibility and this website license do not grant rights to separately licensed Content Packs or SagaSmith Web source. diff --git a/src/pages/developers.astro b/src/pages/developers.astro index a93f486..5fb024e 100644 --- a/src/pages/developers.astro +++ b/src/pages/developers.astro @@ -46,15 +46,30 @@ import { repositories } from '../lib/site';

Browser → API/BFF → Agent worker → Domain MCP

+
+
+

托管运行契约Hosted operating contract

+

可恢复的 Host 工作流，不复制领域权威。A recoverable Host workflow without duplicating domain authority.

+
+
+
DURABLE TURN

RoomTurnJob 跨崩溃恢复RoomTurnJob survives crashes

每个房间动作持久化 queued / running / waiting / succeeded / failed / cancelled 状态、lease、heartbeat、重试与结果引用。浏览器、Web、Agent 和 MCP 复用同一业务幂等键；base_revision 冲突返回可恢复结果，LLM turn 期间不持有房间或数据库锁。Every room action persists queued / running / waiting / succeeded / failed / cancelled state, lease, heartbeat, retries, and a result reference. Browser, Web, Agent, and MCP reuse one business idempotency key; base_revision conflicts are recoverable, and no room or database lock is held for the LLM turn.

+
STANDARD MCP MEDIA

保留 CallToolResultPreserve CallToolResult

Hosted worker 保留标准 MCP text、image、audio、resource 与 embedded-resource 内容。Web 保存原始结果，再通过内部 HostMediaEnvelope 投影为受 audience 约束的私有 artifact/object ID；房间图片与战斗 grid 不需要私有 MCP wire protocol。Hosted workers preserve standard MCP text, image, audio, resource, and embedded-resource content. Web stores the original result, then projects it through an internal HostMediaEnvelope into audience-bound private artifact/object IDs; room images and combat grids need no private MCP wire protocol.

+
RECEIPT PROJECTION

成功 receipt 驱动可重建投影Successful receipts drive rebuildable projections

Web 不直接读取或写入领域权威数据库。成功 MCP receipt 驱动 durable outbox 与带 authority revision、audience 的云端投影；failed、rolled-back 与 no-op 不失效缓存，工具目录也不会因每次战斗写入全量刷新。Web never reads or writes a domain's authoritative database directly. Successful MCP receipts drive a durable outbox and cloud projections carrying authority revision and audience; failed, rolled-back, and no-op work does not invalidate caches, and combat writes do not refresh the entire tool catalog.

+
TASK NEGOTIATION

Host job 不等于 MCP TaskA Host job is not an MCP Task

RoomTurnJob 覆盖整个 LLM turn。MCP Tasks 仅在协商 io.modelcontextprotocol/tasks 且真正长耗时工具返回 claim 后进入 authenticated poll、cancel 与恢复；普通工具保持同步。RoomTurnJob spans an entire LLM turn. MCP Tasks switch to authenticated poll, cancel, and recovery only after io.modelcontextprotocol/tasks negotiation and a claim from a genuinely long tool; ordinary tools stay synchronous.

+
WORKSPACE LIFECYCLE

只清理由 Host 登记的工作区Clean only Host-registered workspaces

稳定 opaque --workspace-id、TTL、LRU、数量与容量上限约束 managed root；启动时恢复崩溃标记，terminal success 清理登记状态。未知、外部、legacy、symlink 或 active 目录保留给 operator 审核。A stable opaque --workspace-id, TTL, LRU, count, and byte limits bound the managed root; startup recovers crash markers and terminal success cleans registered state. Unknown, external, legacy, symlinked, or active directories remain for operator review.

+
TRACE + METRICS

可追踪，不用高基数标签Traceable without high-cardinality labels

traceparent、tracestate 与 baggage 穿过 Web、Agent 与 MCP。service、MCP phase、projection、durable job、quota 与 outbox 指标保持低基数，不使用 user、campaign、room、run 或 tool args 作为标签。traceparent, tracestate, and baggage cross Web, Agent, and MCP. Service, MCP phase, projection, durable-job, quota, and outbox metrics stay low-cardinality and never label by user, campaign, room, run, or tool arguments.

+
+
+

权威所有权Authority ownership

@@ -100,7 +115,7 @@ import { repositories } from '../lib/site';

现代协议、权威语义与发布锁必须跨发行形态一致。Modern protocol, authority semantics, and release locks stay consistent across distributions.

-
DISCOVERY + PROJECTION

稳定目录，按任务投影Stable catalogs, task-scoped projections

现代 Host 使用 server/discover 与确定排序、按 authorization 隔离且可私有缓存的 tools/list。Host 根据 system、phase 与任务把稳定目录的 facade 子集交给模型；工具调用仍由 MCP 重新校验 role、phase 与 revision，目录不会被同一连接的副作用改写。Modern Hosts use server/discover and a deterministically ordered tools/list that is authorization-isolated and privately cacheable. The Host projects a facade subset for the current system, phase, and task; MCP still revalidates role, phase, and revision on every call, and connection side effects never mutate the catalog.

+
DISCOVERY + PROJECTION

稳定目录，最多 16 个任务工具Stable catalogs, at most 16 task tools

现代 Host 使用 server/discover 与确定排序、按 authorization 隔离且可私有缓存的 tools/list。SagaSmith Host 只连接当前 system，并按 system、phase、role 与任务把最多 16 个排序且去重的 facade 工具交给模型；这是 Host 命中率策略，不是 MCP 协议上限。MCP 仍在每次调用重新校验权限与 revision，目录不会被同一连接的副作用改写。Modern Hosts use server/discover and a deterministically ordered tools/list that is authorization-isolated and privately cacheable. A SagaSmith Host connects only the current system and projects at most 16 sorted, unique facade tools for the system, phase, role, and task. This is a Host selection policy, not an MCP protocol limit. MCP still revalidates authority and revision on every call, and connection side effects never mutate the catalog.

ERROR + REVISION

失败可解释，写入可并发验证Failures explain themselves; writes remain concurrency-safe

客户端收到一致的错误结构与 revision 语义；旧 revision 不能通过 UI、Agent 文本或 transport 差异绕过。Clients receive consistent error structures and revision semantics; stale revisions cannot bypass checks through UI, Agent text, or transport differences.

IDEMPOTENCY + AUTHORITY

重试不会复制结算，身份不能由请求自选Retries do not duplicate settlement; requests do not choose identity

幂等键与 caller/workload、requester/resource owner、acting character、audience、room turn、base revision、expiry 均由可信 Host 结构化注入并由 MCP 每次重新验证。模型不能选择权威身份，HTTP 也不接受 token passthrough。Idempotency keys and caller/workload, requester/resource owner, acting character, audience, room turn, base revision, and expiry are injected structurally by the trusted Host and revalidated by MCP on every call. Models cannot choose authoritative identity, and HTTP does not accept token passthrough.

HANDLE + CROSS-CALL STATE

显式状态，不依赖隐藏 sessionExplicit state, never a hidden session

跨调用的 exposure、import、render 等状态使用服务端签发的 opaque handle，或显式 campaign/revision 参数。Handle 绑定 owner 与 TTL，过期返回可恢复错误；它只是名称，不是 bearer capability。Cross-call exposure, import, render, and similar state uses a server-issued opaque handle or explicit campaign and revision parameters. Handles bind an owner and TTL, return a recoverable expiry error, and are names rather than bearer capabilities.

diff --git a/src/pages/start.astro b/src/pages/start.astro index 22d45c5..7ee919f 100644 --- a/src/pages/start.astro +++ b/src/pages/start.astro @@ -144,7 +144,7 @@ uv run nanobot sagasmith start

SagaSmith Web

托管产品不是 Local 的必需后端。The hosted product is not a required Local backend.

-

SagaSmith Web 独立拥有账户、Web session、配额、邀请、协作、Forge、Module Studio 与云端投影；request-scoped worker 使用面向目标 MCP 的专用委托调用同一领域 handlers，不透传浏览器 token，也不直接写领域数据库。SagaSmith Web independently owns accounts, Web sessions, quota, invitations, collaboration, Forge, Module Studio, and cloud projections. Request-scoped workers call the same domain handlers with audience-bound delegations; they neither pass browser tokens through nor write domain databases directly.

+

SagaSmith Web 独立拥有账户、Web session、配额、邀请、协作、Forge、Module Studio、durable RoomTurnJob 与云端投影；worker 只连接当前 campaign system，使用面向目标 MCP 的专用委托，并向模型投影最多 16 个任务工具。它不透传浏览器 token，也不直接读取或写入领域数据库。SagaSmith Web independently owns accounts, Web sessions, quota, invitations, collaboration, Forge, Module Studio, durable RoomTurnJob state, and cloud projections. A worker connects only the current campaign system, uses an audience-bound delegation, and projects at most 16 task tools to the model. It neither passes browser tokens through nor reads or writes domain databases directly.

@@ -164,10 +164,16 @@ docker compose -f compose.yaml -f compose.workspace.yaml up --build
+
+
+

验证托管可靠性边界Verify the Hosted reliability boundary

+

房间 turn 必须以持久状态、lease/heartbeat、幂等键、quota 续租和 base_revision 恢复；MCP 已提交但 Web 尚未发布时重用保存的标准 CallToolResult。text、image、audio、resource 与 embedded resource 由内部 HostMediaEnvelope 转为私有 artifact，不替换 MCP wire contract。RoomTurnJob 也不等同 MCP Task；只有协商能力且长工具返回 claim 后才 poll/cancel。Room turns recover through durable state, leases and heartbeats, one idempotency key, quota renewal, and base_revision. If MCP committed before Web publication, reuse the saved standard CallToolResult. Text, image, audio, resource, and embedded-resource content becomes private artifacts through the internal HostMediaEnvelope without replacing the MCP wire contract. A RoomTurnJob is not an MCP Task; poll and cancel begin only after capability negotiation and a long tool's Task claim.

+
+

按组件锁升级与回滚Upgrade and roll back by component lock

-

生产部署只接受已验证的不可变 Web/Agent/Core/领域 commit 组合。先用锁定版本执行协议与数据 canary，再切换；回滚恢复上一份完整锁及其兼容 schema。不要把归档 split repo、未锁定 main 或 legacy session 状态作为回退输入。Production accepts only a validated immutable Web, Agent, Core, and domain commit set. Run protocol and data canaries against the lock before switching; rollback restores the previous complete lock and compatible schema. Never use an archived split repository, an unlocked main branch, or legacy session state as a fallback input.

+

生产部署只接受 sagasmith.release-lock/v3 中已验证的不可变 Web/Agent/Core/领域 commit 组合。先用锁定版本执行协议与数据 canary，再切换；回滚恢复上一份完整锁及其兼容 schema。不要把归档 split repo、未锁定 main 或 legacy session 状态作为回退输入。Production accepts only the validated immutable Web, Agent, Core, and domain commit set in sagasmith.release-lock/v3. Run protocol and data canaries against the lock before switching; rollback restores the previous complete lock and compatible schema. Never use an archived split repository, an unlocked main branch, or legacy session state as a fallback input.