@continua-ai/wheelie-capability-core

@continua-ai/wheelie-capability-core is the TypeScript SDK/testkit slice for making a local tool, app, or service safely agent-callable with Wheelie capability contracts before relying on hosted infrastructure.

The package is prepared for the first public npm GA release (0.1.0). Registry install commands should be shown only after public npm readback confirms the latest dist-tag, tarball integrity, and fresh install/import smoke.

What is included

• capability descriptor, grant, session, stream event, receipt, support-state, validation-environment, and failure contracts
• descriptor, grant, session, receipt, stream sequence, SSE frame, transition, and redaction validators
• deterministic fake transports, fake receipt sink, grant/session helpers, trace/replay helpers, and local fake invocation harness
• a conformance runner for descriptor validation, grant/session admission, redaction checks, stream sequencing, receipt validation, and trace validation
• copy-pasteable local/fake examples for local notification preview, validation evidence streaming, and repo agent-readiness manifests
• package/gallery manifest, agent card, CapSearch/gallery descriptor, llms.txt, checked local protocol conformance pack, security, support, changelog, provenance, release packet, and status/support-state files
• zero runtime dependencies and no package-manager lockfile

What is excluded

• production grant minting, revocation stores, receipt stores, signing keys, or provider credentials
• hosted relay/control-plane internals, billing or metering internals, operator runbooks, dashboards, and release automation
• browser extension bridges, native app adapters, cloud-vendor SDK bindings, and live transport adapters
• generated runtime packages; generated consumers stay fixture-only until a separate release workflow owns generated-code versioning and provenance

Support state

| Surface | Current state | Safe action | | --- | --- | --- | | Local contracts, fakes, examples, and conformance | native_local | Build locally and run the npm scripts below. | | Package registry install | pending_publish_readback | Use npm install @continua-ai/wheelie-capability-core only after registry readback confirms 0.1.0 on latest. | | Public GitHub read/tag/archive | public_read_verified | Read the public source repo, release/tag, raw docs, and archives; do not infer hosted support. | | Wheelie Source read/evidence | public_read_verified | Read the public Source page, manifest, llms.txt, agent card, archive metadata, checksum, and evidence routes. | | Public artifact status/readback | public_static_readback_live | Use the status page/JSON as the current support-state boundary; npm claims need registry readback. | | Hosted validation | hosted_optional_after_dry_run | Dry-run first after local value is demonstrated. | | Live transports or production grants | unsupported | Use local fakes and conformance fixtures. |

Agent-readable files

Agents and package/gallery readers should use these stable files before making claims or suggesting actions:

• wheelie-package.json — package/gallery manifest with support states, distribution status, trust labels, capabilities, tools, and policy.
• .well-known/agent.json — agent card for inspect, local conformance, local examples, optional hosted dry-run, and unsupported operations.
• .well-known/capsearch.json — CapSearch/gallery descriptor projection.
• llms.txt — agent docs index and safe task cards.
• CONFORMANCE.md, SECURITY.md, SUPPORT.md, STATUS.md, CHANGELOG.md, and PROVENANCE.md — human-readable conformance, security, support, availability, release, and provenance boundaries.
• conformance/cases.json and conformance/expected_report.schema.json — checked local fixture coverage and typed pass/fail receipt schema.
• RELEASE_CANDIDATE.md and release-candidate.json — release packet with package boundary, fixture parity, redaction checks, public-claim ceiling, and local-only examples.

Reading these files is read-only. It must not contact hosted services, create telemetry, upload source, spend money, or mutate team-visible state.

Build and local validation

Build the ESM .mjs JavaScript and .d.mts TypeScript declarations with the package's checked TypeScript build target, then run the package-readiness test before creating an archive.

The readiness test checks package metadata, export-map artifacts, zero-dependency posture, package payload boundaries, checked conformance fixtures, descriptor validation_environment alias compatibility, public metadata redaction, generated-runtime exclusion, private-adapter exclusion, TypeScript compiler options, included examples, local example execution, redaction tests, and a local file-archive install that imports the public ESM conformance runner from outside the source tree.

Run the local examples

The examples use fake providers and local receipts by default. They do not contact hosted services, upload source, install extra packages, request provider credentials, or emit hidden telemetry.

npm run check
npm run example:local-notifier -- --fake --sink stdout \
  --emit-receipt out/local-notifier.receipt.json
npm run example:validation-evidence -- --fake \
  --fixture examples/validation-evidence-stream/fixtures/public-safe/tap.ndjson \
  --emit-receipt out/validation-evidence.receipt.json
npm run example:repo-agent-readiness -- --fake \
  --fixture examples/repo-agent-readiness-manifest/fixtures/public-safe/minimal-repo \
  --emit-manifest out/agent-readiness.json
npm run conformance -- --example local-notifier-capability --offline
npm run test:redaction

Optional Wheelie validation comes after the local path succeeds and remains a dry-run preview:

wheelie validation plan --dry-run --json --recipe local-notifier-capability

Public release claim policy

The first GA npm package supports local contracts, fakes, examples, and conformance. It does not include live transports, production grants, generated runtime packages, source-primary authority, public Wheelie Source writes, marketplace support, seller payouts, paid listings, or live-money support.

Only claim npm availability after the release receipt records unauthenticated registry metadata, /latest, tarball integrity, and fresh install/import readback.