Skip to content

feat(llm-docs): wire the on-disk docs bundle into the extension host - #15251

Draft
midleman wants to merge 11 commits into
mi/bundle-docs-2afrom
mi/bundle-docs-2b
Draft

feat(llm-docs): wire the on-disk docs bundle into the extension host#15251
midleman wants to merge 11 commits into
mi/bundle-docs-2afrom
mi/bundle-docs-2b

Conversation

@midleman

@midleman midleman commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Summary

Wires the docs-bundle cache from PR #15242 into the extension host and exposes it to extensions as positron.docs.getLocalDocs(), so the AI assistant can read Positron docs from disk instead of fetching them from the web.

  • Declares the positron.docs API surface plus the positronLlmsDocsUrl product field, overridable at runtime with POSITRON_LLMS_DOCS_URL
  • Adds IExtHostDocs: node port adapters over http/fs/yauzl, and an always-undefined web-worker variant
  • Adds the trigger layer: launch fetch, getLocalDocs() with a 10s bounded wait, and a mid-session ai.enabled flip
  • Gates every path on ai.enabled, read live
  • Publishes the extension host's startup-finished moment so the launch fetch stays clear of the eager-activation burst

Release Notes

New Features

  • N/A

Bug Fixes

  • N/A

Validation Steps

Manually validated against a local fixture server (POSITRON_LLMS_DOCS_URL=http://127.0.0.1:8099) with a throwaway extension calling getLocalDocs():

Scenario Result
Dev build resolves latest-by-policy Bundle installed to <userdata>/User/positron-llm-docs/<version>/
ai.enabled: false No request at all, undefined, no cache directory
ai.enabled flipped true mid-session Fetch fires with no reload
Two concurrent getLocalDocs() calls One download, both callers served
Bundle 404 undefined, no cache, no state written
Checksum file 404 Zip fetched, install refused, undefined
Digest mismatch Install refused, undefined
Release build, exact bundle published resolution: exact, isExactMatch: true
Release build, exact not yet published HEAD 404 then latest, resolution: fallback
Relaunch on an exact cache Zero network requests
Relaunch on a fallback cache Re-HEADs exact every launch
Exact publishes later Converges to exact, superseded directory deleted
Unchanged bundle, stored ETag Single conditional GET, 304, cache kept
CDN 404 with a warm cache Cached bundle still served
Server slower than the bounded wait undefined at 10s, download continues, next call served
Workbench profile and server-side cache Not run: needs a Workbench container

Decisions are logged under the [llm-docs] in Output > Extension Host:

[llm-docs] fetching http://.../positron-llms-latest.zip (latest-by-policy)
[llm-docs] installed 9999.01.0-1 from http://.../positron-llms-latest.zip
[llm-docs] ai.enabled is off; not serving local docs

QA Notes

Depends on #15242 and must not merge before it.

@midleman midleman changed the title mi/bundle docs 2b Wire the on-disk docs bundle into the extension host Jul 31, 2026
@github-actions

github-actions Bot commented Jul 31, 2026

Copy link
Copy Markdown

E2E Tests 🚀
This PR will run tests tagged with: @:critical @:assistant

Why these tags?
Tag Source
@:critical Always runs (required)
@:assistant Changed files

More on automatic tags from changed files.

readme  valid tags

@midleman midleman changed the title Wire the on-disk docs bundle into the extension host feat(llm-docs): wire the on-disk docs bundle into the extension host Jul 31, 2026
@midleman
midleman force-pushed the mi/bundle-docs-2b branch 4 times, most recently from 62f8825 to ce341d7 Compare July 31, 2026 12:46
@midleman
midleman force-pushed the mi/bundle-docs-2b branch from ccc0548 to 4cd87c6 Compare July 31, 2026 13:01
@midleman
midleman force-pushed the mi/bundle-docs-2b branch from 4cd87c6 to 6194dbc Compare July 31, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant