# wave3d-agent-sdk

/*! NOTICE-ID: WAVE-ENGINE-PROPRIETARY-NOTICE-v1 | Wave Engine Copyright (c) 2026 Wave3D. Proprietary; not open source. Licensed use only. No reverse engineering, decompilation, disassembly, AI-assisted implementation recovery, or notice removal except to the extent of non-waivable law. See LICENSE. */

Same-machine Wave Studio MCP transport plus one immutable WaveEngine authoring corpus.

## License Boundary

Wave Engine is free-to-use proprietary software. It is not open source or source available. This package supports authoring through documented public APIs. It does not authorize implementation recovery. Controlling Wave Engine terms ship in `dist/legal/`.

Machine-readable policy IDs: `WAVE-ENGINE-PROPRIETARY-NOTICE-v1` and `WAVE-ENGINE-AI-POLICY-v1`.

## Start

```bash
npx -y wave3d-agent-sdk@0.3.14 start
```

The SDK listens on loopback only. Localhost MCP uses no bearer token. Keep the Wave Studio tab open so its lightweight browser channel can rendezvous with the SDK even while the tab is not focused.

Transport starts before corpus verification. `GET /health` reports `transportReady`, `corpusReady`, `corpusStatus`, and `corpusError` separately. Live Studio pairing and file tools can connect while the immutable authoring corpus prepares; authoring lookup remains fail-closed until `corpusReady` is true.

## Agent Flow

1. Call `initialize`.
2. Call `self_check_wave_mcp` with the version/build copied by Wave Studio.
3. Complete `get_wave_agent_onboarding` and `accept_wave_agent_onboarding`.
4. Call `tools/list`.
5. Pin the requested Studio tab with `get_wave_session`.
6. For an exact visible-code edit, call the Studio mutation tool directly. Do not run authoring discovery.
7. For unfamiliar WaveEngine authoring, call `query_wave_authoring` once with the user intent and bounded code context.
8. For a generated 3D model, texture atlas, or PBR material, call its concrete local SDK tool directly instead of authoring discovery.
9. Use returned authoring evidence or asset-generation workbench, then edit or operate Studio directly. Stateless structural preflight protects code mutations. Same-call operation diagnostics are authoritative; do not repeat a successful run without a new reason.

`query_wave_authoring` is the only authoring discovery tool. Atomic family/capability tags annotate unified records; they are not a routing hierarchy or second corpus. The package has no secondary search index, remote authoring lookup, legacy lookup tools, or triage path.

Exact public symbols and owner/member queries resolve from API Extractor maps. Natural intent, bounded code context, and compiler-error repair use the same deterministic local lexical projection over public APIs, authoring bodies, focused examples, concepts, and contracts. No embedding model, vector index, hosted lookup, or retrieval-time network path is present.

## Authoring Doctrine

MCP teaches one Wave Engine pattern: choose a legitimate public authoring
object, facade, factory, entity, component facade, or vocabulary object, then
express the intent as one semantic method call or one fluent chain to its
terminal. Prefer native Wave semantics for values, state, placement, animation,
and lifecycle. Keep ordinary scene code synchronous and performance-aware.

The canonical package philosophy is
[`wave-engine/README.md`](../../wave-engine/README.md). The detailed runtime
retrieval source is
[`wave-engine/docs/agentSkills/fundamentals/authoring-model.md`](../../wave-engine/docs/agentSkills/fundamentals/authoring-model.md),
and
[`wave-engine/docs/agentAuthoring/contracts/authoring-constitution.json`](../../wave-engine/docs/agentAuthoring/contracts/authoring-constitution.json).
The packaged corpus is a generated immutable projection; do not hand-edit it.

## Asset Generation

Asset generation is a first-class local SDK workflow, not an API lookup and not a `bootstrap.ts` edit.

- 3D model: `create_wave_3d_modeling_job` -> author and run the returned private Python recipe -> `inspect_wave_3d_model_artifact` -> upload/bind only after acceptance.
- Texture atlas: `compile_wave_atlas` with `operation:"prepare"` -> create the planned PNG sources -> `operation:"compile"` -> `inspect_wave_atlas_artifact` -> upload/bind only after acceptance.
- PBR material: `compile_wave_pbr_material` with `operation:"prepare"` -> retrieve or generate one coherent aligned source set -> `operation:"compile"` -> `inspect_wave_pbr_material_artifact` -> upload only the accepted `.wave-material.zip`.

The model lane owns semantic material slots and simple embedded evidence. Generated high-fidelity reusable PBR maps use the separate material compile+inspect lane; model recipes must not invent or duplicate those image maps.

The package ships its pinned Wave adapter at
`dist/providers/compileArticraftMechanical.py`. Normal SDK operation resolves
that packaged copy automatically. Trusted Articraft imports additionally
require `WAVE_ARTICRAFT_PYTHON` to name the administrator-provisioned pinned
Articraft virtual-environment Python and `WAVE_ARTICRAFT_RECORDS_ROOT` to name
the trusted records authority. `WAVE_ARTICRAFT_MECHANICAL_COMPILER` remains an
explicit administrator override; end users never supply compiler scripts.

Atlas profiles are `uiSkin`, `vfxFlipbook`, `foliageCards`, `spriteAnimation`, `staticMaskAtlas`, and `materialChannels`. Compiler owns packing, padding, trim restoration, channel alignment, hashes, consumer projection, and QC. Agent must not hand-author atlas coordinates.

## Commands

```bash
wave3d-agent-sdk --version
wave3d-agent-sdk start
wave3d-agent-sdk doctor
wave3d-agent-sdk cache status
wave3d-agent-sdk cache refresh
wave3d-agent-sdk cache clear
```

`start`, `cache status`, and `cache refresh` validate and atomically install the immutable package corpus when it is missing, corrupt, or different. `start` performs that work in parallel with the already-listening transport. A refresh of an already-valid identical bundle is idempotent. The CLI never rebuilds retrieval indexes and never downloads a corpus or retrieval model.

## Corpus Contract

The package contains one hash-linked authoring snapshot with:

- API Extractor public contract evidence;
- public API, authoring-body, example, contract, concept, and relationship records;
- family and capability tags as metadata;
- serialized lexical Orama retrieval projection;
- Wave Engine legal SSOT copies and required runtime third-party notices.

Every public callable record must have an owning or supporting authoring body. Internal implementation, source locations, source maps, engine systems, and raw Babylon implementation surfaces are rejected by the package gate.

## Security

- MCP binds to loopback only.
- Studio browser routes require a trusted Wave Studio origin.
- Corpus paths, counts, byte sizes, public-boundary evidence, lexical Orama projection, licenses, and hashes are validated before use.
- Failed corpus preparation leaves loopback transport and Studio pairing available, reports `corpusStatus:"error"`, and keeps authoring lookup fail-closed.
- TypeScript authoring preflight is a fingerprinted lazy runtime module; its compiler core is bundled with required third-party notices instead of installing the full TypeScript package tree at runtime.
- Cache clear refuses dangerous or unmarked custom paths.