diff --git a/AGENTS.md b/AGENTS.md index 6960c1a..ba60bed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,10 @@ accurate historical references. - Present Local Agent Kit and SagaSmith Web as two deployments of the same authoritative MCP contract. Their transport, authentication, storage, and deployment may differ; their tool schemas, rule/state writes, revision behavior, and idempotency may not. +- Describe MCP `2026-07-28` as the modern target: request-scoped discovery and authorization, + deterministic catalogs with Host-selected task projections, and explicit expiring handles for + cross-call state. Treat initialize/session exposure and `tools/list_changed` only as a labeled + compatibility adapter, never as an authority boundary or the long-term model. - Treat repository visibility, software licensing, and Pack/source/asset rights as separate facts. - Do not claim bundled commercial rules or modules. @@ -46,6 +50,8 @@ accurate historical references. Pages workflow aligned with the public routes and data boundaries. - GitHub Pages publishes this repository's static `dist/` only. Do not bundle a domain Workbench or treat another repository as a website release input. +- Release and production deployments consume only validated immutable component locks. Rollback + restores a previously validated lock; it never revives an archived repository as an input. ## Development diff --git a/README.md b/README.md index e3a3ab3..e65014a 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,26 @@ Former standalone MCP, Skills, UI, and generic Module Generator repositories are ## Product boundaries -- SagaSmith Local Agent Kit and SagaSmith Web are two deployments of `sagasmith.authoritative-mcp/v1`. +- 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 diff --git a/scripts/check-content.mjs b/scripts/check-content.mjs index b7dd6e0..dd84a60 100644 --- a/scripts/check-content.mjs +++ b/scripts/check-content.mjs @@ -51,6 +51,13 @@ const authoritativeFiles = [ '.github/workflows/deploy.yml', ]; const authoritativeText = (await Promise.all(authoritativeFiles.map(read))).join('\n'); +const modernContractFiles = [ + 'README.md', + 'src/pages/index.astro', + 'src/pages/start.astro', + 'src/pages/developers.astro', +]; +const modernContractText = (await Promise.all(modernContractFiles.map(read))).join('\n'); for (const legacy of legacyNames) { if (authoritativeText.includes(legacy)) failures.push(`authoritative surfaces still name legacy repository: ${legacy}`); @@ -58,6 +65,20 @@ for (const legacy of legacyNames) { for (const repo of currentRepos) { if (!authoritativeText.includes(repo)) failures.push(`current repository missing from authoritative surfaces: ${repo}`); } +for (const legacyClaim of [ + 'sagasmith.authoritative-mcp/v1', + 'principal-scoped worker', + 'refresh schemas after tools/list_changed', +]) { + if (modernContractText.includes(legacyClaim)) failures.push(`public contract still contains legacy claim: ${legacyClaim}`); +} +for (const file of ['README.md', 'src/pages/start.astro', 'src/pages/developers.astro']) { + const source = await read(file); + if (!source.includes('2026-07-28')) failures.push(`${file}: missing modern MCP target`); +} +for (const requirement of ['server/discover', 'tools/list', 'opaque handle', 'COMPONENT LOCK + ROLLBACK']) { + if (!modernContractText.includes(requirement)) failures.push(`public contract missing modern boundary: ${requirement}`); +} const workflow = await read('.github/workflows/deploy.yml'); if (/repository:\s+SagaSmithAI\//.test(workflow)) failures.push('Pages workflow still checks out an external release input'); diff --git a/src/pages/developers.astro b/src/pages/developers.astro index b95500f..a93f486 100644 --- a/src/pages/developers.astro +++ b/src/pages/developers.astro @@ -17,7 +17,7 @@ import { repositories } from '../lib/site'; @@ -27,7 +27,7 @@ import { repositories } from '../lib/site';

双发行物Two distributions

部署可以不同，领域真相不能分叉。Deployment may differ. Domain truth may not fork.

-

Local 与 Hosted 可以采用不同 transport、authentication、storage 和 deployment。它们必须保持相同 handlers、tool schemas、capability discovery、错误、权限、revision、idempotency 与规则写入语义。Local and Hosted may use different transport, authentication, storage, and deployment. They must preserve the same handlers, tool schemas, capability discovery, errors, authority, revisions, idempotency, and rule-write semantics.

+

Local 与 Hosted 可以采用不同 transport、authentication、storage 和 deployment。它们必须保持相同 handlers、tool schemas、capability discovery、错误、权限、revision、idempotency 与规则写入语义。现代 MCP 每次请求都携带版本、能力与身份元数据，不执行 initialize，也不以连接或 Mcp-Session-Id 建立权威。Local and Hosted may use different transport, authentication, storage, and deployment. They must preserve the same handlers, tool schemas, capability discovery, errors, authority, revisions, idempotency, and rule-write semantics. Modern MCP carries version, capability, and identity metadata on every request; it does not initialize or derive authority from a connection or Mcp-Session-Id.

@@ -36,6 +36,7 @@ import { repositories } from '../lib/site'; @@ -45,7 +46,8 @@ import { repositories } from '../lib/site';

Browser → API/BFF → Agent worker → Domain MCP

@@ -95,12 +97,14 @@ import { repositories } from '../lib/site';

公共契约Public contract

-

六个维度必须跨发行形态一致。Six dimensions stay consistent across distributions.

+

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

-
SCHEMA + CAPABILITY

动态发现，不维护固定工具全集Dynamic discovery, never a fixed tool superset

Host 使用服务端动态工具列表，并在 tools/list_changed 后刷新 schema；phase、role 与 exposure 继续在服务端收窄。Hosts use the server-owned dynamic tool list and refresh schemas after tools/list_changed; phase, role, and exposure narrow capabilities server-side.

+
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.

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

幂等键、principal context、actor binding 与 campaign role 均由可信边界注入并由 MCP 重新验证。Idempotency keys, principal context, actor bindings, and campaign roles are injected by trusted boundaries and revalidated by MCP.

+
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.

+
COMPONENT LOCK + ROLLBACK

整组升级，整组回滚Upgrade and roll back as one set

Local release profile 与 Hosted production 固定经过验证的 Agent、Core、三个领域和 Web commit 组合。切换前执行 modern/legacy、stdio/HTTP 与数据 canary；回滚恢复上一份完整锁及兼容 schema，不把 archived repo、未锁定 main 或旧 session 状态当作输入。Local release profiles and Hosted production pin a validated Agent, Core, domain, and Web commit set. Before switching, run modern/legacy, stdio/HTTP, and data canaries; rollback restores the previous complete lock and compatible schema, never an archived repository, unlocked main branch, or old session state.

PACK CONTRACT

统一内容包，独立权利与激活Unified content packages, separate rights and activation

sagasmith.content-package v2 是当前公开交换格式；每个 Pack 的许可、来源、导入权限与 campaign activation 都独立判断。sagasmith.content-package v2 is the current public exchange format; each Pack's license, provenance, import authority, and campaign activation are evaluated separately.

diff --git a/src/pages/index.astro b/src/pages/index.astro index 9460e44..591093c 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -36,7 +36,7 @@ const news = await loadNews(3);
- DEPLOYMENT MAP / v1 + DEPLOYMENT MAP / MCP 2026-07-28 CONTRACT LOCKED
@@ -50,7 +50,7 @@ const news = await loadNews(3);
HOSTED / WEB PRODUCT

SagaSmith Web

-

浏览器/PWA、API/BFF、协作、Forge 与 principal-scoped Agent worker。Browser/PWA, API/BFF, collaboration, Forge, and principal-scoped Agent workers.

+

浏览器/PWA、API/BFF、协作、Forge 与使用专用委托的 request-scoped Agent worker。Browser/PWA, API/BFF, collaboration, Forge, and request-scoped Agent workers using audience-bound delegation.

account · session · worker
@@ -58,8 +58,8 @@ const news = await loadNews(3);
ONE AUTHORITATIVE CONTRACT - sagasmith.authoritative-mcp/v1 -

同一 handlers、schemas、errors、authority、revision 与 idempotency。The same handlers, schemas, errors, authority, revisions, and idempotency.

+ sagasmith.authoritative-mcp/v2 +

同一 handlers、schemas、errors、每请求 authority、revision 与 idempotency。The same handlers, schemas, errors, per-request authority, revisions, and idempotency.

DOMAIND&D
diff --git a/src/pages/start.astro b/src/pages/start.astro index 22dcb71..22d45c5 100644 --- a/src/pages/start.astro +++ b/src/pages/start.astro @@ -56,7 +56,7 @@ import { localProfiles } from '../lib/site';

Local Agent Kit

从发行锁安装，不依赖旧仓库。Install from the release lock, with no legacy repository dependency.

-

--source release 会使用 Agent 仓库内的发行锁检出所选当前组件。安装器不会导入商业书籍、生成私有 Pack、配置 provider secret 或自动激活内容。--source release uses the Agent repository's release lock to fetch the selected current components. The installer does not import commercial books, create private Packs, configure provider secrets, or activate content.

+

--source release 会使用 Agent 仓库内的不可变发行锁检出所选当前组件。锁同时记录经过验证的 MCP 现代/兼容组合；回滚恢复上一份完整锁，不会改用归档仓库。安装器不会导入商业书籍、生成私有 Pack、配置 provider secret 或自动激活内容。--source release uses the Agent repository's immutable release lock to fetch the selected current components. The lock records the validated modern/compatibility MCP combination; rollback restores the previous complete lock and never substitutes an archived repository. The installer does not import commercial books, create private Packs, configure provider secrets, or activate content.

@@ -126,10 +126,10 @@ uv run nanobot sagasmith start
-

同一契约，三种本地 transportOne contract, three local transports

+

MCP 2026-07-28，同一契约、三种本地 transportMCP 2026-07-28, one contract across three local transports

transport 改变进程形态，不改变规则语义。Transport changes process shape, not rule semantics.

-

每种模式都必须执行同一 handlers、schema、错误、revision、idempotency 与 authority 语义。HTTP 仅监听 loopback。Every mode executes the same handlers, schemas, errors, revisions, idempotency, and authority semantics. HTTP binds to loopback only.

+

每种模式都必须执行同一 handlers、schema、错误、revision、idempotency 与 authority 语义。现代请求使用 server/discover，并在每次调用携带版本、能力与身份元数据；连接或 Mcp-Session-Id 不是权限边界。HTTP 仅监听 loopback。Every mode executes the same handlers, schemas, errors, revisions, idempotency, and authority semantics. Modern requests use server/discover and carry version, capability, and identity metadata on every call; neither a connection nor Mcp-Session-Id is an authority boundary. HTTP binds to loopback only.

stdio

一个本地客户端独占每个 MCP 进程；不开放网络监听。One local client owns each MCP process; no network listener.

@@ -144,7 +144,7 @@ uv run nanobot sagasmith start

SagaSmith Web

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

-

SagaSmith Web 独立拥有账户、session、配额、邀请、协作、Forge、Module Studio 与云端投影；它通过 principal-scoped worker 调用同一领域 MCP，不直接写领域数据库。SagaSmith Web independently owns accounts, sessions, quota, invitations, collaboration, Forge, Module Studio, and cloud projections. Principal-scoped workers call the same domain MCP; Web never writes domain databases directly.

+

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.

@@ -164,6 +164,12 @@ docker compose -f compose.yaml -f compose.workspace.yaml up --build
+
+
+

按组件锁升级与回滚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 WebOpen SagaSmith Web ↗