docs(concepts): session-wrap plugin hook and OpenShell sandboxing - #86
Draft
djsauble wants to merge 3 commits into
Draft
docs(concepts): session-wrap plugin hook and OpenShell sandboxing#86djsauble wants to merge 3 commits into
djsauble wants to merge 3 commits into
Conversation
Extend the plugins page with the one lifecycle hook the scoped prototype ships: session-wrap. Covers the hook tree, the typed top-level [plugin-hooks] section and its two-way binding checks, consent (top-level-only declarations, the auto-activation prompt that defaults to No), the hook protocol (context file and the five environment variables), the session-wrap rules (exec-and-never-return, re-entry marker, nesting and in-place refusal), and the store-path dev loop. Messages are quoted from the flox/flox daniel/session-wrap-hook branch; further extension points stay deferred. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPagejDEz6zqZRXJQZp4Zr
Sandboxing is a plugin built on the session-wrap hook, not a CLI feature. The page walks the declare / consent / enforce pattern, the security properties it rests on, and the OpenShell plugin as its only current implementation: what the hook does, requirements, the manifest policy table, image caching, and limitations. Adds the page to the Concepts nav and regenerates llms.txt. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPagejDEz6zqZRXJQZp4Zr
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
The page's goal is to describe every way to extend Flox, and until now it covered only environment plugins. Frame the two mechanisms up front (environment plugins take part in an environment's lifecycle; subcommand extensions add `flox <name>` commands, installed per user), keep the lifecycle table for environment plugins and say why extensions sit outside it, and add a Subcommand extensions section: dispatch order and bookkeeping variables, reserved names, install/list/remove, the flox-extension.toml manifest, and how a plugin and an extension combine into one project. Facts follow the beta extension subsystem shipped in Flox 1.14.1 behind features.beta. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPagejDEz6zqZRXJQZp4Zr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed Changes
Tightly-scoped cut of #84 (
daniel/plugin-lifecycle-and-sandboxing): documents only thesession-wrapextension point and OpenShell as its only concrete plugin. Tracking: OpenShell Sandbox Plugin (Linear); the code is flox/flox#4677 and flox/flox-plugins#25.concepts/plugins.mdx— adds a two-row lifecycle table (session-wrap, profile.d), the hook tree, the[plugin-hooks]declaration and its two-way binding checks, consent and composition rules, the hook protocol (env vars, ctx fields,invocation_typeshapes), the session-wrap contract, a store-path dev loop, and a debugging addendum. Every quoted prompt, warning, and error string was checked byte-for-byte against the flox branch.concepts/sandboxing.mdx(new) — the sandboxed-activation pattern (declare / consent / enforce), security properties, an OpenShell section (requirements, manifest example, images and caching, limitations), and "writing your own session boundary".concepts/plugins.mdxalso now covers subcommand extensions (the betaflox extensionmechanism, shipped in 1.14.1 behindfeatures.beta), so the page describes every way to extend Flox. Framing: the page opens with "two ways to extend Flox" (environment plugins take part in an environment's lifecycle and are configured per environment; subcommand extensions addflox <name>commands and are installed per user), the lifecycle table stays an environment-plugin table with a sentence on why extensions sit outside it, and a new section covers dispatch order, bookkeeping variables, reserved names, install/list/remove,flox-extension.toml, and how a plugin and an extension combine (aflox vault-secrets checkexample built only on shipped behavior). "Extension point" was renamed to "mechanism"/"hook" on both pages so "extension" means one thing.docs.jsonnav entry;llms.txtregenerated.Open framing question for reviewers. The page keeps its
Pluginstitle and/concepts/pluginsURL (five in-repo links and the manifest section name depend on it) and changes only its description. Alternatives considered: a row in the lifecycle table (rejected: the table's columns are environment phases); a separate Extensions concept page (defer until extensions can be installed from FloxHub and the existing IDE "Extensions" page is retitled); renaming this page to "Extending Flox" keeping the slug (viable now, only the sidebar label and llms line change). Happy to switch.Deliberately not included from #84: env/sidecar/on-deactivate hooks, the other 14 sandbox plugins, and two unrelated fixes on that branch (the vault
secret/example and the run-mode debugging wording) which belong in their own PR.Draft on purpose: prototype docs, reviewed via the Mintlify preview; not for merge before the feature ships. The prototype Warning links to the two sibling branches, so this should merge after they do.
mint broken-linkswas not run locally (mint isn't installed here); internal links and anchors were verified by script (36 links, 0 missing).🤖 Generated with Claude Code
https://claude.ai/code/session_01PPagejDEz6zqZRXJQZp4Zr