lampway_tools

Imported from Keigyoku/lampway (src/scripts/mixar/modules/lampway_tools/AGENTS.md). Install upstream with npx skills add Keigyoku/lampway --skill lampway_tools. Copyright stays with the author.

lampway_tools — the client-side tools

The tools the agent, the panel's buttons, the operators, MCP clients and the live bridge all call inside the running app: api.py is the one door; features/ and pipeline/ hold the tool engines (features/ touches Blender, pipeline/ is mostly pure); meshqa/, rebuild.py, meshpaint.py, jobs.py, runner.py and the *_client.py / *_state.py pairs talk to the server. This directory ships inside the app (everything under src/scripts is installed), so nothing here may be a scratch file, a sample asset or a test. Adding a tool: the lampway-tool-authoring skill; the algorithms: the lampway-canon skill.

Native MetaHuman metacarpals follow their named finger01 continuation beside slide helpers. Rig export defaults follow measured normalized frames with recorded recipe selection; explicit Titan stays available and every raw-frame readback bar stays unchanged. Physical UE M-RIG-01 confirmation remains separate and required.

Boot height-anchor scale uses measured knee-to-sole length, independent of world translation. Verify body-only and both-input translations and retain the sole-at-zero result; earlier height-anchor candidate measurements require a rerun on the corrected source. This geometry correction does not select a physical default among width, height and foot anchors.

The captain authorized AC65 judgment defaults on2026-10-07: facing0.05, pair per_side, collar20mm, boots width and the bounded waist/boots/gauntlets pose tables. Every adopted candidate remains physically untested; executable default-path checks prove routing and refusal controls only. Preserve explicit overrides, side identities/inverse maps and curl-TO targets including thumb. Scene pose receipts require hash-bound placement metadata before rays or writes and report compact blockers in original piece coordinates.

Decision measurements render the actual evaluated body and placed candidate together in fixed world bounds only when explicit context and clearance limits are supplied. Closed-body pseudonormal and open-body winding signs retain an explicit opening-band refusal. Vertex-clearance acceptance remains separate from execution success and full fit acceptance.

Pose region membership follows actual skeleton ancestry to the nearest configured seed, retaining each sample's weighted bone for transformations and ray origins. Refuse empty requested regions and invalid/ambiguous ancestry before pose evaluation or file writes. Component/native synthetic proofs remain distinct from the original body rerun.

ue_parity compares a UE capture only with the UE half's receipt (capture.json, lampway.ue-parity-capture/1), converting its declared inverse-opacity alpha to coverage before silhouettes and edge bands; a capture without that receipt refuses. A class the scene does not sample reports unmeasured, never pass or fail, and so does a region whose samples all fall in the PST edge band; GEO compares silhouettes outside that band (the captain's ruling, 2026-10-11). Parity descriptions carry every lit surface's material. The UE light map's spot cones are the least-squares fit of UE's squared ramp to EEVEE's smoothstep falloff, not outer × (1 − blend).

Invariants

Onboarding Continue and Back rebuild the existing temporary popup with context.region_popup.tag_refresh_ui() and redraw it. Button operator context.region is the surrounding editor; its redraw alone does not rebuild popup content. Retain one popup, padded step height and a shared Back/Continue footer. Verify both transitions in the standalone onboarding suite and the isolated native GUI fixture; native receipt claims remain limited to the measured binary and sampled widget/pixel observations.

Weight transfer warns below the documented majority-match diagnostic threshold and names lampway_fit_place. Validate overrides before creating an output; compare the unrounded fraction and keep this warning separate from export acceptance.

1. One door. The agent's scripts reach a tool only through api.call(name, payload), and only names registered by @tool (TOOL_FUNCS) are callable; the payload is one JSON object.

2. Refusals name the next step. A failure is {"ok": false, "error": ..., "help": [...]}, never a traceback into the model (the @tool wrapper and its _HELP table).

3. The project-root jail. Every path an argument names resolves under settings.project_root (settings.resolve_in_root); outside it is refused with PathOutsideProject. Tools write new files and never overwrite the user's sources; a rebuild tag is never overwritten.

4. Only the user's click confirms a spend. Anything that runs Python for someone else (the agent's executor, a headless worker, the live bridge) runs inside human_gate.scripting(), and the confirm operator refuses while one is on the stack.

5. The scene is touched on the main thread only. Slow work is a job (jobs.py); only its scene-touching tail runs from the app's timer. Background threads never touch bpy.

6. The live bridge serves only its own user. It runs unsandboxed Python, so each connection's peer uid is read from the kernel's socket table and only the app's own uid is served; an unattributable connection or an oversize request is refused (bridge.py).

7. Egress is the server's. A route is switched on only by the user's click (ui/operators/egress_ops.py through egress_client.py); no tool here opens an outbound connection of its own to a provider.

8. Settings resolve environment, then <lampway home>/settings.json, then the default (settings.py); the profile lives under LAMPWAY_HOME and never in the user's stock Blender profile.

9. What an agent may do is the user's click, and the Client holds no default of its own. A capability is switched, its approval or options changed and an agent's proposal accepted only by the user's click (ui/capabilities.py through capabilities_client.py, every write behind human_gate; the first-run walk's step in onboarding.py writes only what the user ticked differently from the server's own defaults). The capability-enabled first-run walk sizes each current step from its actual content and paginates capability rows within a fixed budget, reserving possible warnings so ticks keep their page membership. Setup opens one native popup with explicit footer Back and Continue. Navigation, provider refusal and failed save rebuild that popup's temporary-region layout rather than opening another modal; editor redraw alone is insufficient. Step titles and final-step detection follow the current walk's dynamic steps and kind. Capability paging retains Window.mixar_refresh_popups, preserves choices and writes no settings. Legacy walks retain their existing sizing. Turning on one that runs code or acts outside Lampway shows its plain warning first. The page reads a cache (capabilities_state) filled by a worker thread; a draw never reaches the network, and the page never switches a route. Agent preferences exposes the same server-backed native Hermes delegation, cron and background choices. Every enable action displays the explicit untested layering warning and requires user confirmation; all default off on the server. The warning remains visible when enabled, and scripts cannot confirm it. No client-only copy of these choices is saved. Context settings in the Choices/Capabilities surface follow the same rule: the server supplies defaults and explicit project overrides; the client draws a cache, performs requests off-thread and publishes replies on the main thread. Publication redraws areas and rebuilds open refreshable unanchored popovers through the native window helper; temporary popup regions are outside areas, so area redraw alone leaves the original Context page stale. Edits/reset require the user's click and a matching project; a stale dialog cannot write another project. The UI shows the pinned runtime's live reload and independent summarizer limitations rather than silently restarting a pane or inventing a model window.

   First native-harness launch has its own explicit account notice dialog, separate from route enablement. Its cache-only draw displays safe native status or UNKNOWN; slow preparation and launch stay off the app thread. A script cannot confirm, a cancelled or failed dialog discards its nonce, and stale scene validation refuses before launch. Failed queue callbacks cannot strand later owned responses. Neither notice preparation nor cancellation changes capabilities or login. ChatGPT image qualification opens only from the human Agent preferences action. It obtains an authenticated one-use browser admission off-thread, opens only the fixed local consent page on main-thread publication, and refuses scripts both before scheduling and on publication. The browser form separately confirms the fixed probe. Draw is cache-only; failed browser opening reports a visible error without automatic retry or retaining an ended operator RNA instance.

   Grok Swarm-Worker compatibility is server-owned and defaults off. Agent preferences opens a separate human consent dialog with the exact versioned effects and qualification state. Enable sends the displayed effects digest and version for the captured project/global scope; scripts, cancellation, replay and stale project/scene/disclosure refuse. Reads and enables run off-thread with main-thread scoped publication. Every Mode2 Grok selection, including already-selected MAIN, shows the worker-only disclosure. Continue selects ordinary MAIN without enabling compatibility. No client config/default, route, login or trust grant is created; native readiness remains independent. First-run setup displays this setting and directs the user to its separate Agent preferences review; the generic setup toggle cannot enable it. Client-owned consent, scope, confirmation and recovery messages use explicit extraction markers and translate whole sentences before wrapping. Translated chunks disable label translation; server disclosure strings and their captured digest stay exact.

10. AXI CLI output shares the existing codec. axi.py renders structured stdout through common/toon/codec.py. Standalone CLIs load that authoritative sibling by path without importing Blender. NumPy scalar normalization, lossless numbers, quoting, empty state, next-step commands and refusal exit 1 are retained. Canonical TOON 4.3 output uses the shared encoder's inline primitive arrays and no trailing newline; paired codec bytes and transport are untouched.

11. Native openings and piece facing are measured. Body intake records raw and position-identity analytical topology at 1e-5 m plus generalized head winding. Never weld authored vertices or native weight IDs for publication. Verified head inclusion can admit native openings while retaining closed=false; unverified/headless packages refuse. Signed measurements retain the declared opening-band rule. Raw pieces consume their declared turn once; canonical arrays require zero turn. Non-chest scoring remains unvalidated and native sidecar/source-part refusals remain intact.

12. Visibility admission preserves source state. Export temporarily admits only its requested objects and restores flags. Conform admits only owned output and baseline copies through editing and original deformation verification. An owned temporary visible collection handles excluded source collections without unhiding them. Success and failure restore original selection/active state and copy flags and remove only the owned collection; geometry laws and tolerances remain. Synchronize the view layer before snapshotting selection so removed baseline objects cannot enter the next conform.

13. MCP inspection and view routing. Inspection declares read-only OBSERVE and accepts raw geometry; lampway_view uses raw object/data consumption because explicit focus unhide can edit visibility. The execution pump suppresses automatic undo only for these two tools; view owns its one explicit unhide undo. Only inspection is exempt from the render read-only gate; evaluated inspection still refuses during a render. Inspection adapts caller-owned evaluated geometry into world metres for the shared defect/orientation interfaces, exact uncapped aggregates and precise BVH/parity relations. UV overlap includes triangles within one island while retaining canonical raster semantics. Native admission checks precede cooperative loops and content hashing; the concrete 2M-triangle/100ms refusal is measured, while arbitrary native modifier evaluation remains indivisible. Open-loop rim presentation rounds the full sum once to four metre decimals across inspection and defect candidates.

Failed persistent import consumers remove only the datablocks they imported and restore caller selection. Canonical import ownership includes Library IDs as well as their loaded dependencies: a partial append/link failure must not leave a Library datablock. Studio ownership also includes replacement meshes created while normalizing the imported asset before landing, so a later collection failure removes that replacement. Successful raw intake and persistent imports remain intentional; temporary readbacks clean up on success too. Verify these rules with completed native loads followed by downstream exceptions, preserving existing IDs and selection; subprocess import checks verify failed child isolation without claiming unrelated recipe algorithms.

Body intake measures UV-split topology on analytical positional identities at 1e-5 m, preserving authored vertex/native weight ids. Generalized winding verifies the head and admits measured native openings without claiming watertightness. The MetaHuman normalizer retains corrective fan-out authored frames/roll and records authored_helper_frame; unknown branching bones still require a named continuation. Canon 03/17 and their real-shape covering tests own these rules.

A native weight sidecar and optional GLB preview keep separate source paths and bytes in the body package; supplying both cannot replace engine weights with the preview. Corrective helper endpoints used by weighting come from the validated normalized MetaHuman document and unchanged rest fingerprint; never use a raw imported tail to bypass an unknown branch. Readback imports are transactions over every supported Blender ID collection: both success and partial failure restore pre-import IDs. Independent glove stages use the existing pose and bind engines with recorded labels and body joints; only absent numerical DOF rows stay explicit decisions. The complete canon 08 helmet proposal is accepted and available by name or with scene inputs.

Large receipts from mesh_defect_scan, procedural_library, rig_game_extract and mesh_prep use bounded.py: compact default fields, limit=50 (1..1000), zero-based offset=0, and per-table pages with exact totals. fields selects top-level receipt fields; full=true restores detailed fields while retaining pagination. Explicit legacy max_candidates caps a defect page, while offsets address the complete measured candidate list. Presentation arguments are checked before execution. The covering tests measure default JSON size and verify later pages and full detail.

anim_multiview_fit validates panel paths, calibration shape and positive finite scale/rate before reading input files; its refusal includes a callable template. edit_locality_check accepts the schema's {bbox: [x0, y0, z0, x1, y1, z1]} object as well as the coordinate list, and checks finite coordinates before resolving meshes. uv_islands.measure_object reports the tiles touched using the existing uv_check tile helper alongside its outside-0..1 warning; utilization still measures the 0..1 tile. These changes preserve the canon 11/13 fitting and scoring algorithms.

AXI renders through the authoritative common/toon/codec.py; numpy integer, float and boolean scalars normalize to their native scalar types before TOON formatting. A CLI loading axi.py by file path loads that same sibling codec by path when no package namespace exists; it never imports Blender registration or maintains a second codec. Standalone proportion CLI and numpy-table subprocess tests run with Python -I to prove this path. Refusals use registry-generated tool_specs.json api_calls templates (with specific multiview/locality shapes); normalization helpers and proportion CLI next steps name registered tools rather than Python API names or the old tool shelf.

Plate-facing registration uses four cardinal Workbench silhouettes, the shared native-size plate loader, and canon aspect-preserving IoU. Keep the numeric margin explicit or ruled; unset margins and tied winners refuse, and measurements restore temporary IDs and selection before applying a winning turn.

Recursive receipt presentation also pages large nested arrays and mappings, including B-Bone segment lists and nested mesh metrics; page paths retain original row indices and complete totals. Compact table rows retain their named fields or up to four scalar fields; full detail retains fields while applying the same bounds. Small numeric coordinate vectors remain atomic. QA's external schema requires the actual target object, independently of its optional piece configuration name, and the client verifies that match before creating layers.

Refusal helpers select external API or batch names from generated registry metadata and include the required arguments. Batch failures retain structured refusals even for malformed direct-call names; do not let help generation mask the original error. Cover actual engine validation and recursively inspect nested help/next-step receipts against registered names in the isolated binary, alongside the source-template gate.

Compact mesh_prep retains measured shell orientation and source/current content hashes while paging detailed tables. Motion replacement captures the previous tool-owned output before import; name and stamp the validated replacement only after removing that prior output, preserving caller-owned collisions. Runner truncation bounds the output body separately from the full-path log hint; test both short and over200-character temporary paths.

Test

python -m pytest -q tests/lampway_tools                     # without a binary, the binary-driven tests SKIP: not a pass
LAMPWAY_BIN=build/<env>/bin/mixar python -m pytest -q tests/lampway_tools   # against a built app (syncs Python first)
python -m pytest -q tests                                   # the standalone suites, bpy mocked

tests/lampway_tools/blender_run.py runs a script inside the real binary and reads RESULT {json} lines; it calls scripts/lampway/sync_python.sh before every run, so a Python change needs no rebuild. The server half of each tool is tested in server/tests/test_lampway_tools.py.

Audit the complete measured342-edge native profile before mutation. Anatomical core terminals use canonical parent-line endpoints; exact verified auxiliaries preserve authored frames and are excluded from anatomical convention classification. Share validated/fingerprint-bound endpoints with weighting and posed openings; unknown/reparented edges refuse. Missing native rows are explicit and cannot publish a full body/export.

Canonical rest-frame serialization may project only positive-determinant float32 producer errors within the documented spectral admission budget and unchanged axis bar. Retain valid values, strict CA validation, raw reads/fingerprints and authored matrices; refuse material shear/reflection and retain the hashed full private receipt with bounded public correction metrics.

Owner

The lane whose contract names the tool writes it and its tests; the integration lane lands it. A tool's engine follows its canon page; the canon's open decisions are the captain's.

Engine exports convert metre coordinates on independent centimetre copies and decode only the pinned importer unit carrier. Check raw Null ancestors and direct bone scales before decoding; unchanged bind bars and physical native-reference proof remain mandatory. Never apply a speculative common rotation, mutate source scene units, or hide an authored scale with readback normalization.

The verified native342 conform path requires an explicit reference: source_copy preserves authored rest and skin with an identity map and matching measured convention, while mixed/unknown frames refuse. Default convention exports name only the disposable container Armature under the verified installed UE Blender predicate; occupied names refuse before allocation. For admitted pinned-writer centimetre files, cross-check authored node, BindPose and cluster binds under unchanged shortest-quaternion bars; refuse unsupported layouts without projecting matrices or falling back to inferred display tails. Keep imported display errors visible. Source preservation and authored-file verification never establish independent native UE parity.

Refresh the public copy diagnostic source pins whenever its verified exporter/helper dependency changes. Keep the wrong-overlay refusal and sanitized state-restoration controls; a refreshed hash is diagnostic admission, never engine acceptance.

Complete342 independent native bind conform preserves source heads/skin while carrying each independently referenced engine frame through the fixed writer axis bridge. Require exact reference/source topology, identity mapping and matching reference joints; reject synthesis, IK, offsets and invalid reference rotation/scale. Bind private expected rows and declared writer axes to the output rest fingerprint, and recheck every unchanged canon21 bind bar before recipe selection or authored-file readback. Retain strict joint classification as a separate diagnostic. Weighting/bind consumers may reuse the validated reference convention on this disposable corrected rig; an uncalibrated mixed original remains refused. File/reference checks never assert fresh UE physical parity or original-piece fit acceptance.

Shared auxiliary endpoints admit only the complete verified342 native graph and an established convention, including the checked independent reference receipt. Use each verified auxiliary's authored along axis and length; unknown or reparented helpers refuse. Stamped IK bones retain their authored endpoint when no anatomical continuation exists. Transport rest endpoints through the current pose before weighting or opening consumers use them; never return stale rest endpoints for a posed rig. Source identity, rest fingerprints and unchanged bind-return/piece-acceptance guards remain required.

Uniform rig scaling writes original armature-space rest matrices with scaled translations and lengths through EditBone storage, avoiding recursive parent-local frame reconstruction. Transfer unkeyed pose locations as well as action keys; rollback restores original NLA actions and keys in place. Verify actual head/rest/posed-skin drift under the existing bars separately from independent native-reference calibration and engine acceptance.

Automatic native fit-bone histograms exclude the exact verified auxiliary driver roles after complete-graph endpoint validation. Explicit caller bone choices remain available; a corrective helper is not an inferred anatomical fit target.

Restrict matching selects the nearest normal-compatible triangle in the declared allowed region under the existing distance and angle bars. A nearer incompatible face must not hide it. Named fallback only remaps sampled influences; truly unseeded components retain zero-weight refusal.

Every source vertex must have positive membership in a planned part before weights reads the sidecar or publishes a fit object/state. Uncovered vertices, including faceless orphans, refuse with bounded original IDs and a source-cleanup plan or explicit part-assignment next step. Cleanup stays an explicit copied predecessor with retained identity/face proof, never implicit source removal.

The captain admitted the ARAP-with-clearance candidate under canon03-H2 on2026-10-08 and delegated solver-default judgment. Composite conform requires canonical real-scale mesh admission, immutable source identities, persisted cloth/leather selections, a verified native sidecar and current sampled fit pose. Clearance/seam targets are caller-explicit. Solve creates a disposable candidate with numerical diagnostics and physical_status untested; only unchanged candidate/source/body/pose hashes plus genuine output-render review permit an accepted stage. Bind/weights must use that accepted candidate. Keep rigid metal/ornaments unchanged and refuse nonconvergence, unsafe opening-band signs and stale inputs before admission.

Procedural material probe baking uses one EEVEE frame for three equal-resolution emission tiles only when its reachable coordinate graph is independent of world/camera/external-object state. Each tile retains identical local/object coordinates and the previous linear pixels. Unknown or coordinate-sensitive graphs keep isolated three-frame rendering. Preserve all55 preset tests, the existing240-second per-process limit, caller scene state and owned camera/world cleanup. Resource-profile passes remain distinct from matching-native aggregate acceptance.

Public stage descriptions keep detailed solver input contracts in the linked canon and pending candidate next_args; preserve the measured full MCP catalogue byte ceiling when adding stage guidance.

Multipart normalize_mesh file imports preserve source relative world geometry under one shared declared/recipe turn and union bottom-centre origin. Freeze source world matrices before parent-first baking; record assembly scope in each member receipt. Plate-only multipart facing and animated/constrained assembly transforms refuse before normalization. Auto animation required labels split only terminal side suffixes. Retarget skin checks require target binding and an actual evaluated REST denominator. Bake execution is separate from quality acceptance: in-place treadmill displacement is not world contact, and unmapped weighted bones are named without promoting proposed thresholds. Quaternion publication follows a deterministic bounded normalize-round orbit for profile transform rotations and adapter basis; rebuilding remains exactly byte-equal and hash-checked. Native compare/verify keeps the unchanged A1 bars and numerical closeness does not establish pure packet identity.

Canonical sample publication settles the bounded declared adapter inverse/forward quantized orbit using no retained native data and unchanged packet format, exact hashes and comparison bars. camera_shot render_guides parses its advertised comma-separated pass string and existing direct lists, validates nonempty known tokens before output, and produces only requested guide passes. Preserve omitted-pass defaults, two-pose prerequisite and caller frame/render cleanup. Actual-input pass selection does not certify PBR or fit acceptance.

Weighted unmapped animation channels do not establish the cause of poor skin quality. Retain the true-rest measurements and explicit mapping, offer callable target-weight audit and copy-only cleanup previews, and keep role review and physical acceptance separate from those candidate operations.

Explicit authored FACE-part preparation creates a copied combined mesh with disjoint groups, original vertex/face IDs and a hash-bound original seam ledger. Preserve geometry, UVs, materials, custom data and exact source corner vectors; native normal encoding quantization is measured separately. Bind planning validates source, recipe, ownership and copied topology identities and retains original seam gates despite copied transforms. Separation never accepts source cuts or openings.

Template refits evaluate inside rays against the example's bound REST geometry and restore every armature's pose mode even when evaluation fails. Replacement copies remove inherited Armature modifiers and inherited armature parenting while retaining world placement and untouched originals. Canon20 example weights come from the ray-sized procedural body and nearest-polygon transfer, with each joint owning a quarter of the shorter adjacent bone on both sides. Preserve authoritative prior-art radius and blending rules, original authored vertex identities and genuine outside-joint refusals; algorithm controls do not certify the supplied example's physical motion quality.

The public template tool's centre:rig:<armature> measurement shares canon11 B8 with the view tool. Only the example's own deforming rig supplies REST base heads; open rings and hidden joints retain them. Pin the measured geometry, record all passes and restore source state on every exit. Manual view corrections remain unreviewed candidates and do not bypass outside or copied-fit refusals.

Explicit generated same-shell flexible planar cuts enter fit_bind through bind_overrides._seam_bands. Pin working mesh/world/positive memberships and complete original contact pairs before weights; revalidate before sampling or publication. Use canon07 positional bands before strict rigid fade; no rigid role or source seam acceptance changes. weight_transfer preserves all native influences by default; positive requested caps remain explicit.

Articulated contacts in fit_bind require the source-bound typed declaration and validated authored-part copy. Admit only complete named pair closure under unchanged weld/fade bars, retain undeclared contact domains and rigid one-bone rows, and recheck source/frame/membership/recipe at weights, return and apply. The captain's2026-10-10 shoulder ruling authorizes derived candidate work; full-fit review remains unreviewed until supplied.

Anneal log