package PBS references and expose paginated MCP reads

This commit is contained in:
2026-09-29 08:48:33 +01:00
parent 58f11a8123
commit feb57c5298
23 changed files with 738 additions and 21 deletions
@@ -184,7 +184,8 @@ Reference reads take an opaque ID from that index, not a path or arbitrary URI.
Offset defaults to 0; limit defaults to 4000 and accepts 1–16000 Unicode code
points. A page returns referenceId, offset, total, text and nextOffset (null at
end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the
index. Installed packaging and real provider resolution are steps 17–18.
index. Installed reference content is resolved through the frontend's owner-maintained
reference provider, not a Studio-maintained language specification.
### 5.1 Manifest and Provider Resolution
@@ -230,9 +231,44 @@ symlink targets. SDK entries are always read-only; packaged SDK resources need n
have filesystem roots. Scope metadata does not sandbox an external agent's own
filesystem tools; the developer remains responsible for those tools and Git.
Paths in MCP results are absolute filesystem strings, not `file:` URIs. Until
step 18 packages the owner-maintained index, references/reference IDs are empty
with `DOCUMENTATION_UNAVAILABLE`; no guessed path or reference is advertised.
Paths in MCP results are absolute filesystem strings, not `file:` URIs.
### 5.2 Installed References and Pagination
An installed frontend MAY implement `FrontendReferenceProvider` through
`FrontendProvider.documentation()`. That compiler-side contract supplies indexed,
owner-maintained texts for an SDK major and project target. It does not depend on
Studio API or MCP. Studio projects these into neutral reference descriptors;
full texts MUST NOT be included in project context. Reference IDs are namespaced
by language (`<languageId>:`), unique within the selected project index and opaque
to callers. Studio MUST NOT interpret an ID as a filename, URI or URL.
PBS packages its numbered specifications and informative quickstart from their
owner directory, plus a compilable Game example and actual SDK sources/barrels.
A build-generated index binds these texts to the installed frontend using content
hashes. Distribution-only reads MUST work without a checkout or network. SDK and
example references identify their SDK major and target; unsupported selections
MUST NOT silently reuse another SDK/target. Numbered spec/draft revisions and the
reference-index schema revision MUST NOT be reported as language/compiler versions.
`studio_reference_read` is authenticated but does not require a control grant or
task. It resolves the explicit open root and its current saved manifest selection
on every read. Changing SDK/target can invalidate previously advertised IDs.
Only IDs in that project's installed index can be read, including when other
languages/providers are installed globally. SDK and external-library texts remain
consultable, not editable through this surface.
Pagination counts Unicode code points: an astral character occupies one offset,
not two UTF-16 units. Offset 0/limit 4000 are defaults; limit MUST be 1–16000.
An offset equal to total returns empty text and null nextOffset. Offsets beyond
total, negative offsets, nonintegral values and integers beyond the implementation's
signed 32-bit range are invalid parameters, never wrapped/truncated to another page.
Missing or unreadable provider documentation yields `DOCUMENTATION_UNAVAILABLE`
limitations, not promised references. An uninstalled primary language yields
`UNSUPPORTED_LANGUAGE` for reference reads; an available index without the requested
ID yields `REFERENCE_NOT_FOUND`. Closed projects yield `PROJECT_NOT_OPEN` before
reference lookup. These failures do not grant/revoke task authority.
## 6. Image Contract
@@ -258,7 +294,8 @@ authentication, Origin, endpoint/method/version handling, tool dispatch, malform
or oversized input, closure, restart and old-token rejection. Provider doubles
exist only in tests. Composition starts/closes transport with Studio.
The production registry composes `studio_project_context` as of step 17; other
The production registry composes `studio_project_context` and `studio_reference_read`
as of step 18; other
tools are advertised only when their functional handlers are connected.
DEV configuration-copy stays unavailable until step 21. Passing this transport
gate is not the phase 3 or final external-agent acceptance gate. API/Core and