Skip to content

Generated durable state anchors inside the installed artifact — separate state root from code root (follow-up to #628; #592) #637

Description

@ScriptedAlchemy

Problem

#628 moved only the web-specific plugin-data directory out of the artifact (~/.agent-bundle/web-data/<plugin>-<digest>/<server>). The framework's own generated state owner still anchors inside the installed artifact:

  1. resolveWebLaunch() (packages/agent-bundle/src/web-host/launch.ts) sets AGENT_BUNDLE_PLUGIN_ROOT to the installed artifact — correctly, that is the code root.
  2. resolvePluginRoot() (packages/rsc-runtime/src/plugin-root.ts) computes stateRoot = join(root, 'state').
  3. generatedStateOwner() (packages/agent-bundle/src/build/entry-shell.ts), the lineage journal, the notice store, and the standalone hook wrappers (adapters/hook-contract.ts) open the SQLite driver at pluginRoot.stateRoot.

So a plugin with a conventional workspace-durable src/state.ts tries to create SQLite files under the installed artifact, which may be read-only (marketplace caches, chmod -R a-w installs, shared installs). A read-only install fails to serve its first state-writing tool.

Required change

Separate the code root from the framework state root in the runtime launch/resolution contract:

  • plugin.root (AGENT_BUNDLE_PLUGIN_ROOT) keeps pointing at installed code and assets. It is never pointed at a data directory.
  • A distinct writable state root is resolved identically by every generated shell that shares state — the stdio MCP entry, its Flight worker, the artifact CLI bin and its render worker, the standalone hook wrappers — keyed like the web-data directory (plugin segment + root digest) so two installs never share state and a read-only install launches.
  • An explicit environment override (AGENT_BUNDLE_STATE_ROOT) stays supported and documented as the override, not a workaround.
  • The artifact manifest (feat(manifest): authoritative agent-bundle.manifest.json v2 — consumers read the composite root through the manifest (#592 step 3, #555 W2/S3) #604, v2) must not record the state location as artifact-relative.

Acceptance

  • Packed-pool regression test: build a plugin with a generated MCP server, a web-exposed App and workspace-durable state; make the artifact read-only; launch with no custom state env; invoke a state-writing tool; assert success, that nothing was written beneath the artifact, and that the MCP process and the CLI bin observe the same state.
  • Docs (en + zh) describe the contract; changeset (agent-bundle, @agent-bundle/runtime, minor) notes that existing installs relocate their state.

Follow-up to #628; part of #592.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions