game-learning-runtime 0.2.0__tar.gz → 0.7.0__tar.gz

game_learning_runtime-0.7.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "game-learning-runtime",
+  "interface": {
+    "displayName": "GameLearningRuntime"
+  },
+  "plugins": [
+    {
+      "name": "game-learning-runtime-skills",
+      "source": {
+        "source": "local",
+        "path": "./plugins/game-learning-runtime-skills"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

{game_learning_runtime-0.2.0 → game_learning_runtime-0.7.0}/.agents/skills/glr-adapter-builder/SKILL.md

@@ -10,6 +10,16 @@ Build the smallest truthful adapter that exposes game semantics through GLR.
 Keep `Game Adapter != RL Algorithm`: the runtime side never imports PPO,
 IMPALA, BC, TorchRL, or a learner policy.
 
+## Resolve bundled files portably
+
+This skill is distributed both from a repository checkout and from a plugin
+installation. Resolve the skill root as the directory containing this
+`SKILL.md`; all `scripts/`, `assets/`, and `references/` paths below are
+relative to that root. Do not hard-code a repository-relative `.agents/skills`
+path or a user-profile installation path. When a command is run from the
+project root, set `$skillRoot` to that resolved directory and pass the
+absolute path to the same script from the installed skill root.
+
 ## Start with explicit boundaries
 
 Before editing, state:
@@ -29,17 +39,55 @@ Run the deterministic scaffold once. Choose a generic public environment ID and
 Python package name; do not put a game account, host, PID, HWND, local path, or
 secret in either value.
 
+For a Unity or Unreal project with source access, create an engine-plugin lane:
+
 ```powershell
-python .agents/skills/glr-adapter-builder/scripts/scaffold_adapter.py `
+# Set $skillRoot to the directory containing this SKILL.md before running.
+vx python "$skillRoot/scripts/scaffold_adapter.py" `
   --output adapters/example_adapter `
   --package example_adapter `
   --environment-id example.environment-v1 `
-  --start-mode reset
+  --engine unity `
+  --access source
+```
+
+For an authorized binary-only runtime, create a truthful external-attach lane:
+
+```powershell
+vx python "$skillRoot/scripts/scaffold_adapter.py" `
+  --output adapters/example_external `
+  --package example_external `
+  --environment-id example.external-v1 `
+  --engine unreal `
+  --access external
+```
+
+For an authorized Unity Mono or Unreal runtime that permits third-party mods,
+read [loader-plugins.md](references/loader-plugins.md) completely, verify one
+compatible upstream release, and create a loader-plugin lane:
+
+```powershell
+vx python "$skillRoot/scripts/scaffold_adapter.py" `
+  --output adapters/example_loader `
+  --package example_loader `
+  --environment-id example.loader-v1 `
+  --engine unity `
+  --access loader `
+  --loader bepinex `
+  --loader-version v5.4.23.5
 ```
 
+Use `--engine unreal --loader ue4ss --loader-version v3.0.1` for the UE4SS
+template. Release numbers are examples, not universal compatibility claims;
+refresh them from official upstream sources before scaffolding.
+
 The generated environment is an explicitly synthetic, trainable seam. Replace
 its semantics through Red-Green-Refactor while keeping its conformance and
 configuration tests green. Never present the synthetic seam as live acceptance.
+Loader lanes additionally emit an empty-deny action vocabulary, bounded
+main-thread host skeleton, exact upstream deployment manifest, staged-package
+command, and Agent instructions. They never install into a discovered game
+directory.
 
 ## Research gameplay before defining the contract
 
@@ -80,6 +128,13 @@ Use `glr.training.v1` in `training.json`.
   `minimum_authority: advisory`, documented, bounded, and ablated in tests.
 - Use named scalar signals and `RewardComposer`; never use `eval`, expressions,
   imports, or callbacks loaded from configuration.
+- Route composed signals through `EpisodeRewardGuard` using
+  `reward-safety.json`. Bound positive shaping per step and episode, require an
+  authoritative terminal outcome, and make failed-episode return non-positive.
+- Validate every BC sample or trajectory with `DemonstrationGate` and
+  `demonstration-policy.json`. Default-deny policy-generated, failed, and
+  unknown-provenance samples; never train BC on the learner's own output as if
+  it were expert data.
 
 ## Implement the adapter contract
 
@@ -98,14 +153,39 @@ For process boundaries, compose `BridgeEnvironment -> BridgeDriver -> transport
 deadlines, framing, bounded payloads, target binding, and queue backpressure.
 GLR owns the environment lifecycle and learner-facing contract.
 
+## Reuse the Runtime Host provider boundary
+
+Read [runtime-host.md](references/runtime-host.md) completely before adding a
+new source, loader, or external runtime bridge. Prefer the shared provider
+vocabulary over inventing another environment envelope:
+
+- Unity/.NET semantic providers implement `IRuntimeProvider` from
+  `sdk/csharp/GameLearningRuntime.Provider`;
+- Unreal/native semantic providers implement `glr::runtime_provider` from
+  `sdk/cpp/include/glr/provider.hpp`;
+- training clients use Python `HostBridgeDriver` behind `BridgeEnvironment`;
+  and
+- engine-specific official/BepInEx/UE4SS code remains a thin reviewed
+  bootstrap and main-thread dispatcher.
+
+The current `glr-hostd` release contains only the synthetic conformance
+provider over bounded stdio. Do not claim that a generated live C#/C++ provider
+is connected, authenticated, or target-bound until the local provider transport
+and a bounded authorized runtime trace prove those capabilities.
+
+For a project that already has a reviewed bridge, hand operation to the
+separate `glr-cli` Skill. The standalone Rust `glr` executable is the canonical
+deployment and control entrypoint; use `glr --project . --json doctor` to check
+the generated project boundary. Do not add a Python console-script wrapper or
+make an adapter depend on the CLI implementation.
+
 ## Validate in increasing-risk order
 
 Read [validation-gates.md](references/validation-gates.md) completely, then run:
 
 ```powershell
-uv run pytest
-uv run mypy src
-uv run ruff check .
+vx setup
+vx run check
 ```
 
 Also run adapter-specific synthetic conformance, stale-request tests, malformed
@@ -113,9 +193,29 @@ payload tests, and a bounded authorized runtime trace when available. Publish
 only aggregate conformance evidence. A headless test does not prove live game
 acceptance.
 
+## Package training evidence for reproduction
+
+Run `vx run train` to exercise the generated deterministic synthetic BC smoke
+test, then `vx run reproduce` to verify its `glr.model-bundle.v1` manifest.
+Replace the smoke trainer with PPO, IMPALA, BC, or another learner outside the
+runtime adapter, while continuing to bundle:
+
+- the exact training and runtime-integration configuration;
+- reward-safety and demonstration-provenance policies;
+- source snapshots and dependency lock files;
+- every learner/environment seed;
+- algorithm and framework versions; and
+- checksummed model artifacts and aggregate metrics.
+
+A verified bundle proves artifact integrity and captures a reproduction
+environment. It does not prove equivalent hardware behavior, a live runtime
+integration, or model quality.
+
 ## Rust decision gate
 
 Keep semantic integration and fast-changing contracts in the simplest safe
 language. Move serialization, shared-memory, framing, or batch conversion to
 Rust only after a reproducible benchmark shows that boundary dominates the
-target workload. Preserve Python reference behavior and cross-language fixtures.
+target workload. The standalone Rust CLI is a distribution/control-plane
+decision, not permission to move game semantics or learner algorithms into
+Rust. Preserve Python reference behavior and cross-language fixtures.

game_learning_runtime-0.7.0/.agents/skills/glr-adapter-builder/assets/demonstration-policy.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "glr.demonstration-policy.v1",
+  "allowed_origins": [
+    "human",
+    "scripted-expert"
+  ],
+  "allowed_outcomes": [
+    "success"
+  ],
+  "origin_weights": {
+    "human": 1,
+    "scripted-expert": 1
+  },
+  "outcome_weights": {
+    "success": 1
+  },
+  "reject_unknown": true
+}

game_learning_runtime-0.7.0/.agents/skills/glr-adapter-builder/assets/reward-safety.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "glr.reward-safety.v1",
+  "outcome_signal": "outcome",
+  "shaping_signals": [
+    "progress"
+  ],
+  "max_positive_shaping_per_step": 1,
+  "max_positive_shaping_per_episode": 10,
+  "failure_episode_maximum": 0,
+  "require_terminal_outcome": true
+}

game_learning_runtime-0.7.0/.agents/skills/glr-adapter-builder/assets/templates/AGENTS.md.template

@@ -0,0 +1,18 @@
+# Agent instructions for @@PACKAGE@@
+
+Operate only an owned or explicitly authorized offline/test runtime. @@LOADER_NOTE@@
+
+- Read `agent-interface.json`, `runtime-integration.json`, `training.json`,
+  `reward-safety.json`, and `demonstration-policy.json` before editing.
+- Keep `action_vocabulary` empty until every action has a reviewed semantic mapping.
+- Reject unknown operations and stale episode or expected-step identities.
+- Dispatch engine mutations on the game/main thread and return verified post-state.
+- Treat gameplay research as advisory; never expand authority from a guide.
+- Route composed rewards through `EpisodeRewardGuard`; a terminal failure must
+  never remain profitable after shaping.
+- Validate every BC trajectory with `DemonstrationGate`; never relabel policy
+  output or unknown provenance as expert data.
+- Never add reflection search, arbitrary script/call endpoints, process discovery,
+  anti-cheat bypasses, credentials, or local machine identifiers.
+- Run `vx run check`, then `vx run train` and `vx run reproduce`.
+- Publish only aggregate synthetic conformance until a bounded authorized live trace exists.

{game_learning_runtime-0.2.0 → game_learning_runtime-0.7.0}/.agents/skills/glr-adapter-builder/assets/training-config.json

@@ -24,8 +24,8 @@
     }
   ],
   "reward": {
-    "minimum": -1,
-    "maximum": 1,
+    "minimum": -20,
+    "maximum": 20,
     "terms": [
       {
         "name": "progress",
@@ -34,6 +34,14 @@
         "minimum": -1,
         "maximum": 1,
         "required": true
+      },
+      {
+        "name": "outcome",
+        "source": "runtime",
+        "weight": 10,
+        "minimum": -1,
+        "maximum": 1,
+        "required": false
       }
     ]
   }

game_learning_runtime-0.7.0/.agents/skills/glr-adapter-builder/references/loader-plugins.md

@@ -0,0 +1,70 @@
+# Authorized loader-plugin integrations
+
+Use a loader plugin only when the runtime owner permits mods or instrumentation
+and the test is offline or otherwise explicitly authorized. Check the game
+license, mod policy, anti-cheat policy, engine/runtime version, and exact loader
+release before generating code.
+
+## Choose a supported lane
+
+| Lane | First supported host | Upstream | Default truth |
+| --- | --- | --- | --- |
+| BepInEx | Unity Mono on BepInEx 5 LTS | <https://github.com/BepInEx/BepInEx> | live attach, real time |
+| UE4SS | Unreal Lua mod on UE4SS 3.x | <https://github.com/UE4SS-RE/RE-UE4SS> | live attach, real time |
+
+BepInEx IL2CPP and UE4SS C++ templates are not generated yet. Do not silently
+substitute them for the supported variants. Record the exact compatible
+upstream tag in `deployment/loader.json`; never use `latest` in a reproducible
+adapter.
+
+## Preserve the loader boundary
+
+The loader hosts reviewed game-semantic code inside the runtime. The learner
+stays outside through authenticated, target-bound local IPC. The host must:
+
+1. start a fresh logical GLR episode with `attach`, not claim a physical reset;
+2. keep the action vocabulary empty until reviewed handlers exist;
+3. reject unknown, stale, oversized, or excess queued commands;
+4. apply mutations on the engine/game thread;
+5. return authoritative post-state before advancing the GLR step; and
+6. remove hooks and release owned state when closed or reloaded.
+
+Reuse the engine-neutral provider contracts when the selected runtime can load
+them: C# `IRuntimeProvider` for Unity Mono/BepInEx and C++
+`glr::runtime_provider` for a reviewed native Unreal lane. The current
+`glr-hostd` stdio conformance transport is not authenticated or target-bound and
+therefore cannot yet satisfy this loader boundary by itself.
+
+Do not add object dumpers, unrestricted reflection/object search, arbitrary Lua
+or C# evaluation, generic function calls, process scanning, stealth loading,
+anti-cheat bypasses, or credential access. A loader's upstream capabilities do
+not become GLR action authority.
+
+## Stage deployment without selecting a game for the agent
+
+Run `vx run package-runtime` after the declared host artifact exists. The
+generated packager validates only portable relative paths and writes a
+checksummed payload under `.glr-dist/`. It does not discover, select, or modify
+a game directory. An operator must choose the exact authorized target and
+perform or approve installation separately.
+
+For BepInEx, build the reviewed C# project against operator-provided
+`BEPINEX_ROOT` and `GAME_MANAGED_ROOT` values. Never commit those values. For
+UE4SS, stage the generated Lua mod as data and keep its action table deny-empty
+until the adapter implementation and negative tests are reviewed.
+
+## Validate
+
+- Parse `runtime-integration.json` and prove every required capability.
+- Verify `agent-interface.json` still denies unknown operations.
+- Exercise queue overflow, stale episode/step, unknown action, failed
+  postcondition, reload, and disconnect tests.
+- Run synthetic conformance and the reproducible model-bundle smoke test.
+- Treat actual loader startup and live-game behavior as a separate bounded
+  acceptance gate.
+
+Official references:
+
+- <https://docs.bepinex.dev/master/articles/dev_guide/plugin_tutorial/index.html>
+- <https://docs.ue4ss.com/dev/guides/creating-a-lua-mod.html>
+- <https://docs.ue4ss.com/dev/lua-api/global-functions/executeingamethread.html>

{game_learning_runtime-0.2.0 → game_learning_runtime-0.7.0}/.agents/skills/glr-adapter-builder/references/research-and-reward.md

@@ -52,6 +52,33 @@ produce.
    signals.
 7. Run ablations for each shaping term and inspect behavior, not just return.
 
+## Enforce episode-level reward safety
+
+Term clipping alone does not prevent hundreds of small positive events from
+overwhelming a loss. Load `reward-safety.json` and route every composed step
+through `EpisodeRewardGuard`:
+
+- declare exactly one authoritative, terminal-only outcome signal;
+- cap positive shaping per step and cumulatively per episode;
+- require the outcome signal on every terminal transition;
+- set a failure episode ceiling so a loss cannot retain a positive return; and
+- log accepted and suppressed shaping plus any terminal correction.
+
+Treat the correction as a guardrail, not a substitute for reward design. Audit
+how often it fires and reduce or remove shaping terms that repeatedly consume
+the budget without improving the terminal objective.
+
+## Gate behavioral-cloning data
+
+Every BC trajectory must carry an immutable origin and authoritative episode
+outcome. Load `demonstration-policy.json` and call `DemonstrationGate.validate`
+before adding it to a dataset. The scaffold defaults to successful human or
+scripted-expert trajectories and rejects policy output, failed episodes, and
+unknown provenance. Weighting is explicit data so outcome/origin weighting can
+be reviewed and reproduced. Policy-generated samples may only enter a separate,
+deliberately configured distillation workflow; never silently relabel them as
+expert demonstrations.
+
 Guide-derived recommendations may seed a `reward-hypothesis`, but they remain
 advisory until runtime evidence validates the underlying signal. Even after
 validation, the guide is provenance for the hypothesis; the runtime is the

game_learning_runtime-0.7.0/.agents/skills/glr-adapter-builder/references/runtime-host.md

@@ -0,0 +1,47 @@
+# Runtime Host and provider SDK boundary
+
+Use the Runtime Host to reuse protocol and lifecycle behavior, not to bypass an
+engine's supported loading boundary.
+
+## Current reusable pieces
+
+- Rust `glr`: canonical standalone deployment and Agent control entrypoint. Its
+  release archive carries the matching Runtime Host and both GLR Skills.
+- Rust `glr-hostd`: strict `glr.host.v1`, serialized stdio, 1 MiB hard frame
+  bound, episode/step fencing, synthetic conformance provider.
+- Python `HostBridgeDriver`: explicit absolute executable, no shell, bounded
+  response deadline, no mutating retry, child cleanup.
+- C# `IRuntimeProvider`: .NET Standard 2.0 Unity/BepInEx-compatible semantic
+  provider contract.
+- C++ `glr::runtime_provider`: header-only C++20 Unreal/native semantic provider
+  contract.
+
+Run `vx just host-smoke` and `vx just provider-sdk-check` before adapting these
+surfaces. Preserve flattened dot-separated tensor paths and little-endian GLR
+v1 tensor bytes.
+
+Run `glr --project . --json doctor` before using an existing adapter project.
+Use the separate `glr-cli` Skill for training, capture, queries, knowledge
+transfer, playback, or explicitly authorized `glr update` maintenance.
+
+## Bootstrap choice
+
+| Runtime access | Bootstrap | Provider contract |
+| --- | --- | --- |
+| Unity source | Official Unity plugin/assembly | C# `IRuntimeProvider` |
+| Unreal source | Official Unreal Runtime Module | C++ `runtime_provider` |
+| Unity Mono, authorized mods | Exact compatible BepInEx | C# `IRuntimeProvider` |
+| Unreal, authorized mods | Exact compatible UE4SS or official SDK | C++ provider when native support is reviewed; Lua remains a bounded shim |
+| External official API | Explicit external adapter | Python `BridgeDriver` or future Host provider transport |
+
+Do not generate a universal injector, arbitrary dynamic-library path, process
+scanner, reflection/object dumper, script evaluator, anti-cheat bypass, or
+automatic installation step.
+
+## Capability truth
+
+`host-stdio` proves only one ordered local child-process session. It does not
+prove authentication, OS process identity, exact game target binding, main
+thread dispatch, physical reset, or live post-state. These capabilities belong
+to a future authenticated local provider connection plus the specific engine
+adapter and must fail closed until implemented and accepted live.