llm-messages 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -6,6 +6,20 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-07-23
+
+### Changed
+
+- Documented the boundary between completed Responses API normalization in
+  `llm-messages` and incremental Responses streaming in `llm-sse`.
+- Added public governance, support channels, maintainer responsibilities, and a
+  contributor-to-maintainer path.
+- Replaced the closed Responses coverage roadmap link with a scoped
+  cross-package conformance issue.
+- Included governance and support documentation in the published package.
+- Development tooling overrides `esbuild` to a patched release so a clean
+  install passes `npm audit` while the runtime remains dependency-free.
+
 ## [0.5.4] - 2026-06-29
 
 ### Changed

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive, or
+harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **sebastian@0a.cl**. All complaints will be
+reviewed and investigated promptly and fairly. All maintainers are obligated to
+respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to llm-messages
+
+Thanks for taking the time to contribute. This project aims to be a small,
+dependable, zero-dependency building block, so the bar for changes is clarity
+and correctness over breadth.
+
+## Getting started
+
+The published package supports Node 18+ at runtime. The local development
+toolchain currently needs Node 20.19+ or Node 22.13+ because the lint, test and
+build dependencies follow those active Node release lines. CI keeps the runtime
+floor honest by installing the packed tarball in a separate Node 18 consumer
+smoke.
+
+```sh
+git clone https://github.com/slegarraga/llm-messages.git
+cd llm-messages
+npm install
+```
+
+## Development workflow
+
+Every change should keep the full check suite green:
+
+```sh
+npm run check        # full validation suite
+```
+
+That script runs the same checks individually listed here:
+
+```sh
+npm run format:check # prettier --check
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm test            # vitest
+npm run build       # tsup (ESM + CJS + types)
+npm run examples:check # smoke-test packaged ESM/CommonJS examples
+npm run pack:check  # npm pack --dry-run, with lifecycle output quieted
+npm run pack:smoke  # install the packed tarball and verify runtime/types usage
+```
+
+Run `npm run test:watch` and `npm run format` while developing.
+
+## Release and staging review
+
+Before staging release, fixture, package metadata or published-file changes,
+review the complete worktree, including untracked files:
+
+```sh
+git status --short -uall
+git diff --stat
+npm run check
+npm pack --dry-run --foreground-scripts=false
+```
+
+Confirm that new fixtures, examples and scripts are intentional, and that no
+private source, test, script, config or generated files are included in the
+package dry-run output. Do not publish from a dirty tree whose untracked files
+have not been reviewed.
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main` (e.g. `fix/gemini-id-matching`).
+2. Add or update tests. New behaviour without a test will not be merged.
+3. When adding conformance fixtures, update `docs/conformance-fixtures.md`
+   in the same change so the fixture inventory stays reviewable and the
+   offline harness remains deterministic.
+4. Make sure `format:check`, `typecheck`, `lint`, `test`, `build`,
+   `examples:check`, `pack:check` and `pack:smoke` all pass.
+5. Keep the public API surface small and documented with JSDoc.
+6. Open a pull request and fill in the template.
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/).
+Examples:
+
+```
+feat(gemini): support functionResponse arrays
+fix(anthropic): merge consecutive tool-result turns
+docs: clarify the canonical hub model
+test: cover parallel tool calls
+chore: bump dev dependencies
+```
+
+The type drives the next version bump (`fix` -> patch, `feat` -> minor, a
+`!` or `BREAKING CHANGE` footer -> major).
+
+## Reporting bugs
+
+Open an issue with a minimal reproduction: the input conversation, the target
+provider, what you expected, and what you got. A failing test case is the most
+useful form a bug report can take.
+
+## Scope and philosophy
+
+- Zero runtime dependencies. A dependency needs an exceptional justification.
+- Conversions are total: they never throw on malformed input, they make a
+  deterministic choice and report it through `onWarning`.
+- Provider behaviour is grounded in official documentation. When you add or
+  change a rule, link the source in the PR.

package/GOVERNANCE.md

@@ -0,0 +1,72 @@
+# Governance
+
+`llm-messages` is an independent open-source project and the conversation
+boundary of the provider-portability suite. Governance favors correctness,
+transparent tradeoffs, and a realistic path for contributors to take ownership.
+
+## Current maintainer
+
+- [Sebastian Legarraga](https://github.com/slegarraga) — project direction,
+  releases, security response, and repository administration.
+
+The project currently has a single maintainer. Adding trusted reviewers and
+maintainers is a project goal.
+
+## Decision process
+
+- Small fixes and backward-compatible improvements are decided through
+  pull-request review.
+- New canonical message fields, provider targets, warning codes, or breaking
+  changes should start with a public issue or discussion.
+- Provider mappings must be grounded in primary documentation and reproducible
+  fixtures.
+- Lossy behavior must stay visible through stable warnings rather than being
+  hidden for convenience.
+- When reasonable contributors disagree, the maintainer records the tradeoff
+  and decision publicly.
+
+## Roles
+
+### Contributor
+
+Anyone who reports a reproducible problem, improves documentation, adds a
+reviewed fixture, or lands a code change.
+
+### Reviewer
+
+A contributor with demonstrated understanding of one or more conversion
+surfaces who regularly helps review changes or triage issues.
+
+### Maintainer
+
+A trusted reviewer with sustained, constructive involvement who can merge
+changes, manage issues, and prepare releases. Maintainers are expected to:
+
+- uphold the code of conduct and security policy;
+- require tests and primary-source evidence for provider behavior;
+- preserve deterministic, offline CI and the zero-dependency runtime;
+- disclose conflicts of interest;
+- avoid merging their own substantial changes without another review when a
+  second maintainer is available.
+
+Maintainer access is based on judgment, reliability, project need, and mutual
+agreement. It is never exchanged for sponsorship, stars, or a fixed number of
+pull requests.
+
+## Releases
+
+Releases follow Semantic Versioning. The release workflow runs the full
+validation suite, package dry run, installed ESM/CommonJS/type smoke tests, and
+npm provenance publishing. Breaking changes require a migration note.
+
+## Security and conduct
+
+Security reports follow [SECURITY.md](./SECURITY.md). Community behavior follows
+[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). A maintainer involved in a conduct
+or security concern should recuse themselves when another trusted reviewer is
+available.
+
+## Governance changes
+
+Governance changes use the normal public pull-request process and should explain
+the problem they solve.

package/README.md

@@ -23,6 +23,17 @@ Switching an agent from one provider to another (or running fallback across prov
 
 `llm-messages` handles all of it. Write the conversation once, send it to any provider.
 
+## Project
+
+- [Roadmap](./ROADMAP.md): conformance and portability priorities
+- [Contributing](./CONTRIBUTING.md): development and fixture workflow
+- [Governance](./GOVERNANCE.md): decisions and the path to reviewer or maintainer
+- [Support](./SUPPORT.md): questions and reproducible bug reports
+- [Security](./SECURITY.md): private vulnerability reporting
+- [Conformance fixtures](./docs/conformance-fixtures.md): public compatibility contract
+- [Changelog](./CHANGELOG.md): release history and migration notes
+- [Code of Conduct](./CODE_OF_CONDUCT.md): community standards
+
 ## Install
 
 ```sh
@@ -277,6 +288,19 @@ for Gemini (which reports `STOP`) and Responses API bodies with `function_call`
 items. OpenAI Chat Completions, OpenAI Responses, Anthropic and Gemini tool
 calls without a non-empty string id get a deterministic one.
 
+### Streaming Responses API output
+
+`llm-messages` normalizes completed response bodies and conversations. For
+incremental SSE events, use
+[`llm-sse`](https://github.com/slegarraga/llm-sse)'s
+`parseOpenAIResponsesStream`, then `collectStream` and `toAssistantMessage`
+before converting the completed history here. Keeping the streaming and message
+boundaries separate lets both packages stay small, deterministic, and
+zero-dependency.
+
+The cross-package conformance example is tracked in
+[issue #29](https://github.com/slegarraga/llm-messages/issues/29).
+
 ### Format cheatsheet
 
 |                  | OpenAI                   | Anthropic                        | Gemini                          |
@@ -355,6 +379,9 @@ local validation and production checks.
 Security posture is tracked in [docs/security-posture.md](./docs/security-posture.md),
 including CodeQL, OpenSSF Scorecard, Dependabot and branch rules.
 
+Questions, reproducible bugs, and maintainer responsibilities are documented in
+[SUPPORT.md](./SUPPORT.md) and [GOVERNANCE.md](./GOVERNANCE.md).
+
 ## Related
 
 `llm-messages` is the conversation boundary in a small provider-portability

package/ROADMAP.md

@@ -7,13 +7,15 @@ fallback behavior matter.
 
 ## Current priorities
 
-1. **OpenAI Responses API coverage**
+1. **OpenAI Responses API boundary**
 
-   Initial response normalization now maps Responses API `output_text` and
-   `function_call` items back into the current OpenAI Chat Completions-compatible
-   hub shape. Next: expand multimodal and streaming conformance fixtures.
+   Completed response normalization maps Responses API `output_text`,
+   `function_call`, refusal, and supported multimodal items into the current
+   OpenAI Chat Completions-compatible hub shape. Incremental SSE normalization
+   belongs in `llm-sse`. Next: prove the cross-package handoff from a streamed
+   function call into portable Anthropic and Gemini histories.
 
-   Public issue: https://github.com/slegarraga/llm-messages/issues/6
+   Public issue: https://github.com/slegarraga/llm-messages/issues/29
 
 2. **Provider-backed fixture refreshes**
 
@@ -33,6 +35,11 @@ fallback behavior matter.
    Document the recommended flow for converting one conversation across
    providers after rate limits or retryable provider failures.
 
+5. **Reviewer and maintainer growth**
+
+   Make fixture ownership, review expectations, and the path to repository
+   responsibility explicit in [GOVERNANCE.md](./GOVERNANCE.md).
+
 ## API credit use
 
 If API credits are available, they will be used for conformance checks against

package/SUPPORT.md

@@ -0,0 +1,41 @@
+# Support
+
+`llm-messages` is maintained in public on a best-effort basis.
+
+## Questions and design discussions
+
+Use
+[GitHub Discussions](https://github.com/slegarraga/llm-messages/discussions)
+for integration questions, proposed conversion behavior, and help choosing the
+right API.
+
+## Bugs
+
+Open a
+[bug report](https://github.com/slegarraga/llm-messages/issues/new?template=bug_report.yml)
+with:
+
+- the source and target provider/API surfaces;
+- a minimal, sanitized message or response body;
+- the canonical output, warning, or finish reason you expected;
+- the package and Node.js versions;
+- a reproduction or failing conformance fixture when possible.
+
+Do not include API keys, private prompts, personal data, or proprietary model
+output.
+
+## Security
+
+Do not open a public issue for a vulnerability. Follow
+[SECURITY.md](./SECURITY.md) to use GitHub private vulnerability reporting or
+the listed security email.
+
+## Scope
+
+The project can help with message and completed-response normalization.
+Incremental SSE event parsing belongs in
+[`llm-sse`](https://github.com/slegarraga/llm-sse). Provider account access,
+billing, rate limits, and general SDK support belong with the provider.
+
+No response-time guarantee is offered, but well-scoped reproductions and pull
+requests are prioritized.