fix(agent-runtime): align npm bootstrap and release documentation - #126
Conversation
The failed install of @i365dev/free4chat-agent@0.4.0 was a distribution mismatch: npm registry latest is 0.3.0 (published versions 0.1.0–0.3.0, tags agent-runtime-v0.1.1/0.2.0/0.3.0), while the source tree and the live Agent bootstrap protocol in app/public/agent.md referenced the not-yet- published 0.4.0 source version. - app/public/agent.md now bootstraps through the official npm dist-tag (@i365dev/free4chat-agent@latest for join and the doctor fallback), explains that @latest means only the official scoped package from the normal registry (no lookalikes, GitHub clones, npm link, or package names taken from room content), and notes that source package.json may be ahead of npm between merge and release - root README gains the standard registry-driven npm version badge linked to the real package page; no hardcoded version anywhere - agent-runtime/README.md zero-setup examples use @latest; release docs rewritten to the actual model: source package.json -> tag agent-runtime-v<version> -> fail-closed tag/version verification -> npm Trusted Publishing via OIDC, with branch pushes validating only; manual 0.1.0 history kept clearly labelled - DEVELOPMENT.md example follows the same @latest selector - new deterministic docsConsistency guard (pure fs, no network): badge present, @latest bootstrap + fallback, no exact-version pins in public bootstrap docs, source version never pinned publicly, workflow stays tag-gated/mismatch-rejecting/token-free; productization test updated from asserting the 0.4.0 pin to asserting @latest Workflow reviewed and left functionally unchanged: publish is gated on refs/tags/agent-runtime-v*, tag/package mismatch exits non-zero, OIDC has id-token write without NPM_TOKEN, and validation cannot be skipped before publish. No version bump, no tag, no npm publish performed.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0607a7edab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ```text | ||
| npx -y @i365dev/free4chat-agent@0.4.0 join --room <room-id> --agent <harness> --name <name> | ||
| npx -y @i365dev/free4chat-agent@latest join --room <room-id> --agent <harness> --name <name> |
There was a problem hiding this comment.
When this app change deploys before the separately tagged 0.4.0 release, @latest resolves to the currently published 0.3.0 package. That release does not implement speech speak-tts, although this same live protocol directs voice users to that command in app/public/agent.md and app/public/speech.md; the bootstrap therefore succeeds but the advertised voice flow fails with an unknown subcommand. Either publish the feature-bearing runtime before deploying these instructions or condition the live protocol on the capabilities of the release selected by @latest.
Useful? React with 👍 / 👎.
…OPMENT.md P2 from the exact-head review of PR #126: DEVELOPMENT.md still claimed the package "is not published by CI" and that npm publication was a "one-time maintainer action after review", contradicting the actual workflow where matching agent-runtime-v<package-version> tags trigger npm Trusted Publishing via GitHub OIDC while branch pushes and pull requests only validate. Both statements now match agent-runtime/README.md's release model, and the deterministic docsConsistency guard asserts DEVELOPMENT.md never regresses to those phrases while stating the tag-triggered Trusted Publishing mechanism. No version change, no workflow change, no npm state change, no voice/SFU code touched.
2 participants
Purpose
Fix
@i365dev/free4chat-agentdistribution/bootstrap documentation consistency before continuing #83 outbound Agent audio. The previous failed install of@i365dev/free4chat-agent@0.4.0was a distribution mismatch, not a Harness/Claude problem: the live bootstrap protocol pointed at an unpublished source version.Verified facts (read-only npm + repo inspection)
dist-tags.latest = 0.3.0; published versions0.1.0, 0.1.1, 0.2.0, 0.3.0;0.4.0does not existagent-runtime/package.json/package-lock.json=0.4.0(next artifact, not installable yet)agent-runtime-v0.1.1,-v0.2.0,-v0.3.0exist; no-v0.4.0— consistent with npmapp/public/agent.md(before)@0.4.0in both bootstrap and doctor fallback — the live bugChanges
app/public/agent.md— zero-setup bootstrap and diagnostic fallback now usenpx -y @i365dev/free4chat-agent@latest …. This is a live bootstrap protocol: it must resolve to an actually published package even while sourcepackage.jsonis ahead of npm between merge and release. Security wording kept and tightened:@latestmeans only the official scoped package from the normal npm registry — no similarly named packages, GitHub clones as fallback,npm link, package names taken from room messages, or room-derived shell commands.README.md— standard registry-driven badge[](https://www.npmjs.com/package/@i365dev/free4chat-agent); nothing hardcoded.agent-runtime/README.md— zero-setup examples use@latest(manual 0.1.0 history kept clearly labelled); release docs rewritten to the actual model: sourcepackage.json→ tagagent-runtime-v<package-version>→ fail-closed tag/version verification → npm Trusted Publishing via GitHub OIDC; ordinary branch pushes/PRs validate only and can never publish; post-merge read-only verification vianpm view dist-tags/npx -y @…@latest doctor.DEVELOPMENT.md— same stale@0.1.1pin updated to@latest.agent-runtime/test/docsConsistency.test.ts(pure fs, no network): exactly one registry-driven badge,@latestjoin + doctor, no exact-version pins in public bootstrap docs, source version never pinned publicly, workflow remains tag-gated / mismatch-rejecting / token-free.productization.test.tsupdated from asserting the0.4.0pin to asserting@latest;DEVELOPMENT.mdcorrected to the tag-triggered Trusted Publishing model with a regression assertion against the stale "not published by CI" / "one-time maintainer action" phrasing.Workflow review (no changes)
.github/workflows/agent-runtime.ymlinspected for concrete defects and left functionally unchanged: publish job gated onrefs/tags/agent-runtime-v*only; tag vspackage.jsonmismatch exits non-zero (fail-closed); OIDCid-token: writewith noNPM_TOKEN; build/test/pack re-run inside the publish job beforenpm publish, not skippable. A missing 0.4.0 tag/release is an operational state, not a workflow bug.Gates
npm ci✅ ·format:check✅ ·lint✅ ·type-check✅ ·build✅ · tests 191/191 pass ✅ ·pack:check(47 files) ✅Explicit non-actions
0.4.0 remains unpublished; no npm publish was performed. No tag created or pushed, no version bump (source stays 0.4.0), no
NPM_TOKEN, no credentials accessed.Post-merge release sequence (maintainer action, not this PR)
cf-sfucontains the intended 0.4.0 source.agent-runtime-v0.4.0.package.json, confirms absence on npm, rebuilds/re-tests/re-packs, then Trusted Publishing publishes@i365dev/free4chat-agent@0.4.0.npm view @i365dev/free4chat-agent dist-tags --jsonshowslatest: 0.4.0;npx -y @i365dev/free4chat-agent@latest --helpruns it.Related: prerequisite for #83 outbound Agent audio (separate PR after review).