@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/continuum.md

@@ -0,0 +1,153 @@
+# Continuum Scene and Package publication
+
+Continuum is HELIX's content-addressed publication path. The Creator package owns
+every operation; MCP tools only pass an absolute descriptor path to the same
+library used by its CLI.
+
+Use `publish_continuum_source_map` for imported maps,
+`publish_continuum_scratch_world` for semantic primitives, and
+`publish_continuum_package` for an already-frozen Package/Build.
+Use `pull_continuum_package` to fetch an exact creator source bundle before an
+agent edits it. The tool delegates authorization, CID verification, path safety,
+and extraction to Creator CLI; it never executes downloaded hooks. After the
+agent updates the self-contained files and its included/compiler-produced
+publication descriptor, `publish_continuum_package` creates the new immutable
+Package Version through the normal fenced workflow.
+
+For an existing creator-owned Item, `publish_owned_item` moves its Package pin
+to one exact public, sealed, current Package Version using the approved
+Publications workflow. It requires explicit content-rating attestation, creates
+no Item or offer, and returns the Creator CLI result without MCP assuming its
+receipt shape. Create Marketplace or World offers separately and only when
+intended.
+
+Devices use the same self-contained definition in both host contexts. An owned
+Home placement persists only its declared durable variables to the Item Instance
+CAS API. A World-embedded copy has no inventory identity, so the World host
+selects session-only or World storage and a namespace for that instance. The
+package never chooses its authority or storage destination; it emits the same
+typed state changes in either host. Host-owned typed Ports/Links connect
+compatible package instances without giving either package direct access to the
+other. Link topology belongs to the containing Home/World/Build, so remixing a
+World can rewire Devices without mutating their exact package versions.
+
+`create_device` supports `standing-desk`, `clock`, and `television`. The TV
+template demonstrates a surface-bound Screen/App, universal text input for a
+YouTube URL/video id, browser-owned origin permission, playback/volume state,
+and typed power/volume/audio ports. Cross-origin video is a sandboxed DOM
+compositor aligned to the authored screen node (browser security does not allow
+an arbitrary YouTube iframe to become a WebGL texture); local canvas/video apps
+may use native CanvasTexture/VideoTexture adapters. Remote web content always
+requires the viewer's global or per-package/per-origin grant.
+
+Use `test_device` with `mode=both`, then publish, pull, edit, validate, test, and
+publish a new version. A Package does not need a Marketplace or Vault Listing.
+Device and other authored content must enter HELIX as a sealed Package Version
+before it is offered as a product. MCP exposes Package publication here. The
+upcoming Creator CLI commands `helix continuum publish-glb` and
+`helix continuum make-item` are intended to seal GLB content and optionally
+project an Item through the approved Publications workflow. Use them only after
+that CLI release is available; consult its help for arguments and rely on its
+response for the result.
+Private and grant-scoped Package inspection/object reads stay ACL-protected even
+when another user knows the exact Package id, version, manifest CID, or object
+CID.
+
+For the bounded Pacifica release canary, use `dry_run_continuum_canary` first and
+then `publish_continuum_canary`. The canary composes the selected materials,
+vehicle and character Packages and Builds, child Scenes, root Scene, Listings,
+Universal Item pins, and World Release as one dependency-linked Package graph.
+The MCP publication path is private/unlisted only. A public canary must be
+confirmed by a human through the Creator CLI; MCP has no confirmation field and
+cannot synthesize one.
+
+## Source and scratch descriptors
+
+A source descriptor contains `projectId`, optional `sourceDigest`, `source`,
+`compilation`, required `defaultRuntimeProfileId`, optional
+`packagePublication`, `objects`, and optional `listing`.
+The source form uses a `SourceSceneMap` (`actors`, shared `materials`, and
+canonical material Package pins). The scratch form uses:
+
+```json
+{
+  "projectId": "project.mall",
+  "defaultRuntimeProfileId": "web-balanced",
+  "source": {
+    "id": "scene.mall",
+    "title": "Mall",
+    "elements": [
+      { "id": "building.mall", "type": "building" },
+      { "id": "floor.spawn", "parentId": "building.mall", "type": "floor", "center": [0, 0], "elevation": 0, "size": [8, 8], "thickness": 0.2 },
+      { "id": "wall.front", "parentId": "building.mall", "type": "wall", "start": [-20, 0], "end": [20, 0], "height": 8, "thickness": 0.3 },
+      { "id": "spawn.main", "parentId": "building.mall", "type": "gameplay-anchor", "transform": { "position": [0, 0.2, 0], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] }, "runtimeModule": { "packageId": "40000000-0000-4000-8000-000000000002", "version": "1.0.0", "manifestCid": "cid:sha256:<spawn runtime manifest sha256>" }, "anchor": "spawn.main" },
+      { "id": "light.sun", "parentId": "building.mall", "type": "light", "kind": "directional", "transform": { "position": [0, 20, 0], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] }, "color": "#ffffff", "illuminanceLux": 10000 }
+    ]
+  },
+  "compilation": {
+    "packageId": "40000000-0000-4000-8000-000000000001",
+    "version": "1.0.0",
+    "provenance": { "kind": "authored", "source": "agent" },
+    "dependencyClosures": [{ "package": { "packageId": "40000000-0000-4000-8000-000000000002", "version": "1.0.0", "manifestCid": "cid:sha256:<spawn runtime manifest sha256>" }, "root": { "cid": "cid:sha256:<spawn runtime object sha256>", "bytes": 123, "mediaType": "application/json", "role": "gameplay-definition" }, "objects": [{ "cid": "cid:sha256:<spawn runtime object sha256>", "bytes": 123, "mediaType": "application/json", "role": "gameplay-definition" }] }],
+    "runtimeProfiles": [{ "schema": "helix.continuum.runtime-profile/1", "id": "web-balanced", "platform": "web", "renderer": "three-webgl2", "quality": "balanced", "contracts": { "continuum": 1, "scene": 2 }, "capabilities": ["render.primitive/1"] }],
+    "world": { "releaseId": "40000000-0000-4000-8000-000000000003", "worldId": "40000000-0000-4000-8000-000000000004", "maxPlayers": 32, "contentRating": "teen", "requiredCapabilities": ["render.primitive/1"] }
+  }
+}
+```
+
+Native structural elements support building/group/level/space hierarchy, walls,
+floors, ceilings, host-bound openings, doors/windows bound to openings, stairs,
+primitives, foliage, explicit-unit lights, portals, gameplay anchors, and child
+Scenes. Interior spaces inherit portal residency. Mesh CIDs, multi-slot bindings,
+trim sheets, source fallbacks, proxy/collider objects, and material Package pins
+remain separate and exact.
+
+During source-map preparation, convert an actor only when its structural meaning
+is proven. Otherwise preserve the exact mesh object and material binding in the
+same graph; never flatten it into a guessed primitive or emit a separate
+per-actor Package graph.
+
+World and Release IDs, generic Package IDs, and every referenced Package ID are
+UUIDs. Source/scratch authoring may supply a stable symbolic label only for its
+new root Scene Package or Release; Creator converts those labels to deterministic
+UUIDs before any API call. `worldId` always names an existing owned World.
+`defaultRuntimeProfileId` is required and must select a web `three-webgl2`
+profile using Continuum 1 and Scene 2. Publication also requires a renderable
+exterior/structural shell, explicit-unit lighting, a `spawn.*` gameplay anchor
+whose Runtime Module is pinned in the dependency closure, authored collision
+beneath spawn, and non-empty `beforeSpawn`/`firstFrame` ReadySets. Creator emits
+the ReadySets; the backend repeats the exact spatial and closure proof.
+
+## Object sources
+
+Every Package-owned object other than the generated Scene document appears once:
+
+```json
+{
+  "reference": { "cid": "cid:sha256:<64 hex>", "bytes": 1234, "mediaType": "model/gltf-binary", "role": "source-mesh" },
+  "source": { "kind": "file", "path": "assets/chair.glb", "audience": "private" }
+}
+```
+
+`kind` is `file` (path relative to descriptor), `vault-adoption` (exact Vault
+Asset Version ID), `instant-world-adoption` (Build ID + authoritative content
+SHA-256), or `existing`. CID, size, media type, Package closure, dependencies, and
+ReadySet reachability are validated before publication.
+
+A creator-editable descriptor may also declare
+`"sourceDirectory": { "path": "source", "audience": "private" }`. Creator CLI
+packages that confined tree into one canonical source object and pins it in the
+Package Version. A source edit changes the source CID and publication job
+identity. Runtime-only legacy Packages remain usable, but `pull_continuum_package`
+will explicitly report that they need source conversion before remix.
+
+## Resume, receipts, and public Listings
+
+The lowercase-normalized source digest plus normalized intent yields a durable
+job ID. A retry or a duplicate worker resumes missing stages and returns one sanitized receipt; use
+`get_continuum_publication_receipt` later.
+
+MCP can never grant public Listing authority. A public Vault or Marketplace
+Listing succeeds only when an owner/editor previously configured the project
+policy. Otherwise the operation fails before creating the Listing. A human may
+instead run the same Creator CLI command with `--confirm-public-listing`.

package/docs/items.md

@@ -0,0 +1,73 @@
+# Package backed Items and offers
+
+Authored content enters HELIX as a sealed Continuum Package Version. Package
+publication and Vault discovery do not create an Item or a creator copy. An
+Item is an optional product projection of an exact Package Version. Marketplace
+and World offers are explicit and use the Creator's approved Publications
+workflow. Do not upload a loose GLB to create an unpinned Item.
+
+Use `read_doc({ name: "continuum" })` and `publish_continuum_package` for Package
+publication. The upcoming Creator CLI commands `helix continuum publish-glb`
+and `helix continuum make-item` are intended for GLB-to-Package publication and
+optional Item creation through the approved Publications workflow. Use them only
+after that CLI release is available; consult its help for arguments and rely on
+its response for the result. `publish_owned_item` is for moving an existing
+creator-owned Item to an exact sealed Package Version; it does not mint an Item
+or create an offer, and requires explicit content-rating attestation. This MCP
+server does not expose a loose-mesh Item publish tool or define publication
+receipt fields.
+
+World-local consumables, currencies, passes and effects remain World Products.
+They do not mint universal Items. There is no raw `grantItem(itemId)` API.
+
+## World code
+
+World code requests an acquisition; the HELIX shell displays authoritative item,
+issuer, price, edition, supply/remaining/next-serial facts, limits and schedule,
+then requires a player click.
+
+```ts
+await Helix.marketplace.purchaseDistributionKey('postcard', { quantity: 2 });
+await Helix.marketplace.purchaseDistribution('public-distribution-id', { quantity: 1 });
+await Helix.marketplace.purchaseListing('listing-for-serial-12');
+
+const context = await Helix.marketplace.getPurchaseContext('dkey:postcard', { quantity: 2 });
+```
+
+Only `dkey:`, `distribution:` and `listing:` are item-acquisition references.
+Item-definition ids, raw internal product ids, caller-supplied prices and silent
+grants are rejected.
+
+## Collectible resale economics
+
+All resale uses HELIX Marketplace escrow. The creator royalty is fixed at 5%.
+The seller platform fee is 10% for Free and 5% for Plus at launch; future Gold
+is 2.5% and Diamond is 0%. Total seller deduction is therefore 15%, 10%, 7.5%
+or 5%. The buyer has no surcharge. Creator self-sale omits a redundant royalty
+transfer, and self-purchase is prohibited.
+
+Every acquisition starts one unified 24-hour relisting cooldown. There is no
+account-age or special first-resale delay. Basic requires email. General
+**Verified** means one unique verified mobile plus good standing and allows
+resale immediately subject only to that acquisition cooldown. Identity Verified
+is reserved for later high-risk capabilities; tooling must also tolerate the
+future Business Verified enum. Resale proceeds use a 3-day base payout hold that
+risk may extend up to 15 days. Relisting eligibility and payout availability are
+separate timestamps.
+
+## MCP contract
+
+MCP delegates operations to the Creator CLI and exposes Package publication
+through `publish_continuum_package` plus the approved existing-Item pin move
+through `publish_owned_item`. It does not expose loose-mesh Item creation or
+define Publications receipt fields.
+
+## Refresh a published item's thumbnail
+
+`item_thumbnail` runs the same library as `helix item thumbnail refresh|set`
+in-process (no CLI step) and needs a CLI that ships it (`helix.minCliVersion`).
+
+- `action: "refresh"` re-renders the canonical thumbnail from the item's active Package Version. Start with `dryRun: true`; pass `force: true` to re-render a thumbnail the server reports as current.
+- `action: "set"` with `imagePath` uploads your own png/jpg/webp (moderated). It is kept across version moves until a later forced refresh.
+- To correct a Package-backed avatar mesh, seal a new Package Version and move the item onto it (the move refreshes the thumbnail unless you uploaded one), or refresh explicitly.
+- Owner-only (403 otherwise). A backend that predates the routes answers 404, reported as "does not support thumbnail refresh yet".