OpenMA Common

Shared, product-agnostic contracts used by OpenMA Desktop and Open Managed Agents. This repository is consumed directly from Git; it is intentionally not published to npm.

Exports

• @openma/common/brand — canonical token names, light/dark values, and brand RGB.
• @openma/common/brand/tokens.css — matching CSS custom properties.
• @openma/common/brand/openma-logo-mark.svg — canonical OpenMA vector mark.
• @openma/common/session-events/managed — Managed Agents wire-event normalizer and turn projector.
• @openma/common/session-events/acp — ACP event parser and chat-turn reducer.
• @openma/common/session-kernel — canonical local/cloud lifecycle, relay commands, and wire conversion.
• @openma/common/acp-runtime — shared ACP session/runtime implementation used by both Backchat and OpenManaged.
• @openma/common/acp-runtime/node-spawner — shared Node subprocess adapter for the ACP runtime.
• @openma/common/session-ui — shared Session turn frame and status semantics with product-specific content slots.

projectCanonicalChatTurns() adapts Managed events into the same TurnRender model used by Backchat. This is the migration seam for a shared Session GUI; the current OpenManaged Console can move to it without changing its API wire format.

Adapters keep wire-protocol differences at the boundary. Consumers may add product-specific presentation after normalization, but should not fork the shared parsing and reduction logic.

Install from Git

Use an immutable release tag in package.json:

{
  "dependencies": {
    "@openma/common": "github:openma-ai/openma-common#v0.4.0"
  }
}

The lockfile resolves that tag to an exact commit. Built dist/ output is committed, so consumer installs do not run package lifecycle scripts. Never move an existing tag; create a new one for every consumer-visible change.

Fast local development

No npm or GitHub release is needed while iterating. From this repository, the single-command flow links all consumers, starts the common watch build, and restores the original dependencies on exit:

pnpm install
pnpm dev:consumers

Run the consumer's normal dev server in another terminal, for example pnpm --dir ../openma-desktop dev or pnpm --dir ../open-managed-agents/apps/console dev. Press Ctrl+C in the common terminal when finished.

For more control, pnpm dev starts only the common watch build; pnpm link:consumers and pnpm unlink:consumers can be run independently. The helper expects openma-common, openma-desktop, and open-managed-agents to be siblings. It swaps only each consumer's node_modules/@openma/common symlink (including the two ACP wrapper packages) and never edits a manifest or lockfile.

Change lifecycle

1. Add or update tests here before implementation.
2. Run pnpm verify.
3. Link the package locally and verify both consumers.
4. Merge the common change, bump version, then create an immutable vX.Y.Z tag.
5. Update each consumer's Git ref and lockfile in an ordinary reviewed PR.

Compatibility policy:

• patch: fixes or additive fields that do not change existing output;
• minor: new tokens, exports, normalized event variants, or optional behavior;
• major: removed/renamed tokens, exports, types, or changed reducer semantics.

See CONTRIBUTING.md for the release checklist.