Consume npm Packages

Outcome

An independent agent app can install agentOS through versioned npm packages instead of sharing the agentOS source workspace lockfile.

Prerequisites

• Distribution boundary
• npm distribution

Steps

1. Install required packages with semver versions.
2. Use the published @yansirplus/* package names.
3. Install required peers such as effect.
4. For prepublish first-party work, run a local registry channel: bun run registry:local, then bun run publish:local in agentOS.
5. Read dist/internal-npm/local-channel.json.
6. Copy the required dependencies entries into the consumer app. Use the logical tag value, for example agentos-dev; do not copy worktree tarball paths. Configure @yansirplus:registry once in the consumer .npmrc only when consuming the local channel.
7. Run the app typecheck and tests under its own lockfile.

For first-party prepublish work, use the local channel instead of hand-writing tarball paths:

bun run registry:local
bun run publish:local

Consumer .npmrc:

@yansirplus:registry=http://127.0.0.1:4873

Consumer package.json:

{
  "dependencies": {
    "@yansirplus/ag-ui": "agentos-dev",
    "@yansirplus/runtime": "agentos-dev"
  }
}

Every publish:local call generates one unique prerelease version and moves the agentos-dev dist-tag. The consumer lockfile pins the resolved package version; the package manifest stays stable across worktrees.

References

• npm distribution
• Runtime packages