llm-messages 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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
+
+- Documentation: add provider-SDK recipes (OpenAI, Anthropic, Vercel AI SDK), a "why not alternatives" section, complete cross-links to the sibling packages, and install / bundle-size badges. No code changes.
+
 ## [0.5.3] - 2026-06-29
 
 ### Fixed

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

@@ -6,11 +6,10 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/slegarraga/llm-messages/badge)](https://scorecard.dev/viewer/?uri=github.com/slegarraga/llm-messages)
 [![license](https://img.shields.io/npm/l/llm-messages.svg)](./LICENSE)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
+[![install size](https://packagephobia.com/badge?p=llm-messages)](https://packagephobia.com/result?p=llm-messages)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/llm-messages?label=min%2Bgzip)](https://bundlephobia.com/package/llm-messages)
 
-Convert chat conversations between **OpenAI**, **Anthropic** and **Gemini**
-message formats, and normalize provider responses into the same
-OpenAI-compatible assistant shape. Tool calls, system prompts, roles and
-response metadata handled correctly. Zero dependencies.
+One library to write a conversation once and send it to OpenAI, Anthropic, or Gemini: handles system prompts, tool calls, role names, consecutive-turn merging, and response normalization. Zero dependencies.
 
 Switching an agent from one provider to another (or running fallback across providers) means rewriting the whole conversation, and the differences are subtle enough to break at runtime:
 
@@ -24,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
@@ -57,6 +67,116 @@ const gemini = toGemini(messages);
 //      contents: [{ role: 'user', parts: [{ text: "What's the weather in Paris?" }] }] }
 ```
 
+## Recipes
+
+### Convert an OpenAI conversation to Anthropic and call the SDK
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { toAnthropic, responseFromAnthropic, type OpenAIMessage } from 'llm-messages';
+
+const client = new Anthropic();
+
+const conversation: OpenAIMessage[] = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'What is 2 + 2?' },
+];
+
+const { system, messages } = toAnthropic(conversation);
+
+const raw = await client.messages.create({
+  model: 'claude-opus-4-8',
+  max_tokens: 256,
+  system,
+  messages,
+});
+
+// Normalize the response back to the OpenAI-compatible shape:
+const { message, finishReason, usage } = responseFromAnthropic(raw);
+const text = raw.content.find((b) => b.type === 'text')?.text ?? '';
+// message.role === 'assistant', finishReason === 'stop', usage.outputTokens > 0
+```
+
+### Provider-fallback loop: one conversation, two providers
+
+When a provider is rate-limited or unavailable, retry against the next one without
+rewriting the conversation or the response-parsing logic:
+
+```ts
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+import { toAnthropic, responseFromAnthropic, responseFromOpenAI, type OpenAIMessage } from 'llm-messages';
+
+const conversation: OpenAIMessage[] = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Summarize the water cycle in one sentence.' },
+];
+
+async function callWithFallback() {
+  // Try OpenAI first:
+  try {
+    const oai = new OpenAI();
+    const res = await oai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: conversation,
+    });
+    const raw = res.choices[0].message.content ?? '';
+    return responseFromOpenAI(res);
+  } catch {
+    // Fall back to Anthropic with the same conversation:
+    const ant = new Anthropic();
+    const { system, messages } = toAnthropic(conversation);
+    const res = await ant.messages.create({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 256,
+      system,
+      messages,
+    });
+    return responseFromAnthropic(res);
+  }
+}
+
+const { message, finishReason } = await callWithFallback();
+// message.role === 'assistant' regardless of which provider answered
+```
+
+### Vercel AI SDK: keep your conversation portable
+
+```ts
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { toAnthropic, type OpenAIMessage } from 'llm-messages';
+
+const conversation: OpenAIMessage[] = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Hello!' },
+];
+
+// Use directly with Vercel AI SDK (already OpenAI-compatible):
+const { text } = await generateText({ model: openai('gpt-4o-mini'), messages: conversation });
+
+// Or convert the same conversation to send via Anthropic SDK:
+const { system, messages } = toAnthropic(conversation);
+```
+
+## Why not X
+
+**`ai` (Vercel AI SDK)** covers model routing and streaming well, but its
+`CoreMessage` type differs from OpenAI's Chat Completions shape, and it does not
+export converters to/from raw Anthropic or Gemini wire formats. `llm-messages` is
+a complement: convert once so the conversation stays in one shape, then hand it to
+whichever SDK or HTTP client you use.
+
+**Writing the conversion yourself** is straightforward for text, but subtle for
+tool calls: argument serialization differs per provider, consecutive same-role
+turns are rejected by Anthropic and Gemini, Gemini matches results by name when
+ids are absent, and Anthropic `tool_use_id` pairing has its own rules. The edge
+cases accumulate. `llm-messages` has conformance fixtures that cover them.
+
+**LangChain / LlamaIndex** solve orchestration. If you only need the message
+conversion layer without the orchestration overhead, `llm-messages` is ~6 KB
+min+gzip with zero runtime dependencies.
+
 ## API
 
 ### The canonical hub
@@ -168,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                          |
@@ -246,21 +379,21 @@ 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.
 
-## Provider portability suite
+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
-suite for OpenAI-compatible agent infrastructure:
-
-- [`tool-schema`](https://github.com/slegarraga/tool-schema) converts one JSON
-  Schema into provider-specific tool/function schemas.
-- [`llm-sse`](https://github.com/slegarraga/llm-sse) parses streaming provider
-  responses into unified events.
-- [`llm-errors`](https://github.com/slegarraga/llm-errors) normalizes provider
-  errors, retry hints and fallback decisions.
-- [`json-from-llm`](https://github.com/slegarraga/json-from-llm) extracts JSON
-  before it enters a tool or message pipeline.
-- [`llm-portability-demo`](https://github.com/slegarraga/llm-portability-demo)
-  shows the whole flow offline, with no API key required.
+suite for OpenAI-compatible agent infrastructure. The other packages in the suite:
+
+- [`json-from-llm`](https://www.npmjs.com/package/json-from-llm): extract valid JSON from an LLM response, even inside reasoning tags, fenced blocks or prose
+- [`tool-schema`](https://www.npmjs.com/package/tool-schema): convert a JSON Schema into a provider tool / function-calling schema for OpenAI, Anthropic, Gemini and MCP
+- [`llm-sse`](https://www.npmjs.com/package/llm-sse): parse streaming SSE from LLM providers into typed, provider-agnostic events
+- [`llm-errors`](https://www.npmjs.com/package/llm-errors): normalize provider errors (rate limits, retries, status) into one shape
+
+The [`llm-portability-demo`](https://github.com/slegarraga/llm-portability-demo)
+shows the whole flow offline, with no API key required.
 
 Read the
 [provider portability map](https://github.com/slegarraga/llm-portability-demo/blob/main/docs/provider-portability.md)

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.