@gripforgeai/mcp 0.1.15 → 0.1.17

package/dist/architecture-tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod/v4';
 import { LOOK_DESCRIPTION, LOOK_VALUES } from './look.js';
-export const ARCHITECTURE_TOOL_NAMES = ['gripforge_architecture_schema', 'gripforge_generate_building', 'gripforge_generate_district', 'gripforge_environment_module'];
+export const ARCHITECTURE_TOOL_NAMES = ['gripforge_architecture_schema', 'gripforge_generate_building', 'gripforge_generate_district', 'gripforge_environment_module', 'gripforge_urban_building'];
 /** Hosted and local MCP share the same recipe and durable server workflow. */
 export function registerArchitectureTools(register, options, schema = z) {
     const identifier = schema.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/);
@@ -10,6 +10,8 @@ export function registerArchitectureTools(register, options, schema = z) {
         name: schema.string().min(1).max(100).optional(), prompt: schema.string().min(3).max(300),
         style: schema.enum(['realistic', 'stylized', 'lowpoly', 'handpainted']).optional(),
         look: schema.enum(LOOK_VALUES).optional().describe(`${LOOK_DESCRIPTION} Fills style when style is omitted; toon, anime and pixel add their phrase to the prompt.`),
+        provider: schema.enum(['meshy', 'tripo']).optional().describe('3D provider pinned to this recipe, Meshy by default. Tripo v3.1 requires one reviewed concept (no multiview yet) and uses v3.5 PBR textures. No automatic paid provider fallback.'),
+        tripoQuality: schema.object({ geometry: schema.enum(['standard', 'detailed']).optional(), texture: schema.enum(['standard', 'detailed', 'extreme']).optional() }).strict().optional().describe('Tripo-only quality; default detailed geometry and detailed textures. extreme requests 8K. Read the separate provider quote. Exclusive with Meshy meshQuality and source.'),
         use: schema.enum(['residential', 'retail', 'office', 'industrial', 'mixed']).optional(),
         floors: schema.number().int().min(1).max(30).optional(),
         dimensions: schema.object({ width: schema.number().min(3).max(100).optional(), depth: schema.number().min(3).max(100).optional(), height: schema.number().min(3).max(150).optional() }).strict().optional().describe('Maximum footprint and height in metres. Uniform fit preserves proportions; actual dimensions are returned.'),
@@ -18,6 +20,7 @@ export function registerArchitectureTools(register, options, schema = z) {
         concept: ref.optional().describe('Owned PNG/JPEG/WebP revision for Meshy image-to-3D. At most 12 MiB. Mutually exclusive with source.'),
         concepts: schema.array(ref).min(1).max(4).optional().describe('Coherent views of ONE building, front first, for Meshy multi-image-to-3D. Exclusive with concept/source. Review coherence before building.'),
         meshQuality: schema.object({ geometry: schema.enum(['standard', '2k', '4k']).optional(), texture: schema.enum(['2k', '4k', '8k']).optional() }).strict().optional().describe('Meshy 7.1 quality. Defaults standard geometry and 2K PBR. Multi-image supports standard/2k geometry only. Texture resolution is preserved during optimization. Read the updated quote.'),
+        delivery: schema.object({ lods: schema.array(schema.object({ triangles: schema.number().int().min(1000).max(200000), textureSize: schema.union([schema.literal(1024), schema.literal(2048), schema.literal(4096), schema.literal(8192)]), maxError: schema.number().min(0).max(.02).optional(), lockBorder: schema.boolean().optional() }).strict()).min(1).max(3) }).strict().optional().describe('Preserve an immutable full-detail source without provider remeshing, then prepare 1–3 independent LOD GLBs. Highest detail first, decreasing triangles and texture sizes. Default maxError=.001, lockBorder=true prioritizes detail and may exceed targets. For distant levels, explicitly allow e.g. maxError=.005/.01 and lockBorder=false after review. Shared metric fit and preserved PBR. No normal rebake, runtime LOD switching or inferred collision. Also works with source at no provider cost.'),
         source: ref.optional().describe('Reuse an owned static GLB revision instead of paying for this building. The source is never modified.'),
     }).strict();
     const material = schema.record(schema.string(), schema.unknown()).describe('SceneMaterialOverride: color, roughness, metalness, map/normalMap/roughnessMap/metalnessMap as owned immutable SceneAssetRef, repeat:[u,v]. Validated by the shared Scene Engine.');
@@ -42,18 +45,19 @@ export function registerArchitectureTools(register, options, schema = z) {
         palette: schema.object({ stone: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), recess: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), trim: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), water: schema.string().regex(/^#[0-9a-f]{6}$/i).optional() }).strict().optional(),
     }).strict();
     const definitions = [
-        { name: ARCHITECTURE_TOOL_NAMES[0], kind: 'schema', shape: {}, title: 'Architecture · schema', description: 'Read the reusable Meshy building and district contract, example, limits and plan → build workflow. Separate immutable Library assets, scene instances and shared SceneDocument. No paid generation.' },
+        { name: ARCHITECTURE_TOOL_NAMES[4], kind: 'urban', title: 'Manufacture a reusable urban building', description: 'Free, deterministic parametric architecture. plan validates a metric recipe; build queues a durable common-compute job and returns job_id to poll with gripforge_generation_read. Real window reveals, balconies, shopfronts, rooftop HVAC, photographic PBR and optional arid shutters/canopies/water tanks. Private immutable GLB plus recipe/report; reuse via Library bindings or scene instances. Nominal width/depth exclude protrusions: use returned actual bounds and preserve proportions. A solid envelope with storefront depth, not traversable interiors, a complete city or an AI replacement for gripforge_generate_building. Review in the actual game. 0 credits.', shape: { stage: schema.enum(['plan', 'build']).optional(), workspace_id: schema.string().max(100).optional(), idempotency_key: shared.idempotency_key, recipe: schema.object({ name: schema.string().min(1).max(100), style: schema.enum(['brick', 'balconies', 'limestone', 'loft', 'workshop', 'office', 'stucco']), width: schema.number().min(6).max(30).optional(), depth: schema.number().min(6).max(30).optional(), floors: schema.number().int().min(1).max(20).optional(), seed: schema.number().int().min(0).max(2147483646).optional(), shop: schema.number().int().min(0).max(7).optional(), climate: schema.enum(['temperate', 'arid']).optional(), palette: schema.object({ facade: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), stone: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), trim: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), roof: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional() }).strict().optional() }).strict() } },
+        { name: ARCHITECTURE_TOOL_NAMES[0], kind: 'schema', shape: {}, title: 'Architecture · schema', description: 'Read the reusable Meshy/Tripo building and district contract, example, limits and plan → build workflow. Separate immutable Library assets, scene instances and shared SceneDocument. No paid generation.' },
         { name: ARCHITECTURE_TOOL_NAMES[1], kind: 'building', shape: { ...shared, recipe: building,
                 stage: schema.enum(['plan', 'concept', 'build']).optional().describe('plan is free: exact prompts and separate image/3D quotes. concept creates reviewable workspace images. First review artistic scene, then isolated views of the SAME building, then build 3D from chosen isolated references.'),
                 concept_provider: schema.enum(['openai', 'xai']).optional().describe('Default openai (GPT Image 2.5 Sunburst, high quality). xai explicitly selects Imagine. Provider is pinned in the durable job; never silently falls back. Read the provider-specific concept_quote.'),
-                concept_presentation: schema.enum(['scene', 'isolated']).optional().describe('Default scene: artistic concept in its neighbourhood preserving the user atmosphere and lighting. isolated: technical views of the SAME building for Meshy. Keep rich architectural detail in both.'),
+                concept_presentation: schema.enum(['scene', 'isolated']).optional().describe('Default scene: artistic concept in its neighbourhood preserving the user atmosphere and lighting. isolated: technical views of the SAME building for 3D reconstruction. Keep rich architectural detail in both.'),
                 concept_reference: ref.optional().describe('Owned artistic reference to EDIT into new scene/isolated views. Distinct from recipe.concept, which reuses an existing front view without generation. Exclusive with recipe.concept/concepts/source and stage=build.'),
-                concept_views: schema.array(schema.enum(['front_right', 'front_left', 'rear_right', 'rear_left'])).min(1).max(4).optional().describe('Unique views starting with front_right. Default one view for scene, three for isolated. Alternate views edit the SAME master. recipe.concept reuses an existing master; concept_reference guides a NEW master.'),
-            }, title: 'Generate a building', description: 'Reusable plan → artistic concept → isolated reference views → review → Meshy build workflow. Generate 1–4 coherent images through OpenAI (1536×1024 high quality, default) or Imagine (2K), saved as private Library drafts; alternate views reference one master. Separate explicit budgets for concepts and 3D. Accepts text, owned single/multiple concept views or an owned static GLB. Meshy PBR/geometry quality, bounded geometry and uniform metric fit. Durable jobs return workspace links; poll generation_read, cancel/retry preserves finished steps. Review images before building and the real Studio render before publishing. No guaranteed interiors, collisions or LODs. Never substitutes procedural geometry or automatically replaces a game asset.' },
-        { name: ARCHITECTURE_TOOL_NAMES[2], kind: 'district', shape: { ...shared, recipe: district }, title: 'Generate a district', description: 'Plan then build a straight-street district from 1–8 distinct Meshy buildings, each manufactured once and reused as separate editable instances. Includes road, pavements, spawn, daylight and camera in the shared Map SceneDocument. Optional owned PBR road/pavement maps; otherwise simple solid surfaces. Plan returns layout, provider-credit count and account quote without spending. Build requires a budget and returns a persistent job, then Map Studio link. Private work version requiring visual review; no automatic Community publication or game replacement.' },
+                concept_views: schema.array(schema.enum(['front_right', 'front_left', 'rear_right', 'rear_left'])).min(1).max(4).optional().describe('Unique views starting with front_right. Default one view for scene or Tripo, three for isolated Meshy. Tripo requires one view. Alternate views edit the SAME master. recipe.concept reuses an existing master; concept_reference guides a NEW master.'),
+            }, title: 'Generate a building', description: 'Reusable plan → artistic concept → isolated reference views → review → Meshy or explicitly selected Tripo build workflow. Generate 1–4 images through OpenAI or Imagine; alternate views reference one master but must be checked for actually different viewpoints. If edits repeat the front, use one good concept instead of a false multiview set. Separate explicit budgets for concepts and 3D. Accepts text, owned concept views or a static GLB. Optional delivery preserves the source master and prepares reusable LOD GLBs with PBR and a common metric fit. Durable jobs return workspace links; poll generation_read, cancel/retry preserves finished steps. Review the actual render before publishing. No guaranteed interiors, collisions or runtime LOD switching; no automatic game replacement.' },
+        { name: ARCHITECTURE_TOOL_NAMES[2], kind: 'district', shape: { ...shared, recipe: district }, title: 'Generate a district', description: 'Plan then build a straight-street district from 1–8 distinct Meshy/Tripo buildings, each manufactured once and reused as separate editable instances. Includes road, pavements, spawn, daylight and camera in the shared Map SceneDocument. Optional owned PBR road/pavement maps; otherwise simple solid surfaces. Plan returns layout, provider-credit count and account quote without spending. Build requires a budget and returns a persistent job, then Map Studio link. Private work version requiring visual review; no automatic Community publication or game replacement.' },
         { name: ARCHITECTURE_TOOL_NAMES[3], kind: 'module', shape: { stage: schema.enum(['inspect', 'build']).optional(), recipe: moduleRecipe, name: schema.string().min(1).max(100).optional(), workspace_id: schema.string().max(100).optional() }, title: 'Create a reusable environment module', description: 'Free parametric 3D masonry, independent of any game: pillar, arch, fountain, stairs, wall, pavement, rock, cliff, ruin, bridge, watchtower, shrine or a stone guardian. inspect (default) returns real generated bounds, triangle count, metric recipe and assembly sockets. build saves a private textured GLB in the Library, with bevelled geometry, baked vertex shading and named stone/recess/trim/water materials. Dimensions are nominal metres; bounds report actual moulding overhang. Ground origin, stairs ascend toward -Z, <=23 cm risers; top/bottom sockets support assembly. Seed and palette are repeatable. Does not place assets, generate arbitrary AI models, publish, or guarantee navigation/collisions in a target game. 0 credits.' },
     ];
-    for (const tool of definitions)
+    for (const tool of definitions.sort((a, b) => ARCHITECTURE_TOOL_NAMES.indexOf(a.name) - ARCHITECTURE_TOOL_NAMES.indexOf(b.name)))
         register(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.shape,
             annotations: { readOnlyHint: tool.kind === 'schema', destructiveHint: false, idempotentHint: tool.kind === 'schema', openWorldHint: tool.kind !== 'schema' } }, async (args, extra) => {
             const parsed = schema.object(tool.shape).strict().safeParse(args);
@@ -64,10 +68,10 @@ export function registerArchitectureTools(register, options, schema = z) {
                 return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
             const { workspace_id, ...body } = parsed.data;
             try {
-                const response = await fetch(options.apiUrl.replace(/\/$/, '') + (tool.kind === 'module' ? '/api/v1/environment-modules' : '/api/v1/architecture'), {
+                const response = await fetch(options.apiUrl.replace(/\/$/, '') + (tool.kind === 'module' ? '/api/v1/environment-modules' : tool.kind === 'urban' ? '/api/v1/urban-buildings' : '/api/v1/architecture'), {
                     method: tool.kind === 'schema' ? 'GET' : 'POST',
                     headers: { 'content-type': 'application/json', 'x-gripforge-client': 'mcp', ...(key ? { 'x-api-key': key } : {}), ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) },
-                    ...(tool.kind === 'schema' ? {} : { body: JSON.stringify(tool.kind === 'module' ? body : { ...body, kind: tool.kind }) }),
+                    ...(tool.kind === 'schema' ? {} : { body: JSON.stringify(['module', 'urban'].includes(tool.kind) ? body : { ...body, kind: tool.kind }) }),
                     signal: AbortSignal.any([AbortSignal.timeout(60_000), ...(extra?.signal ? [extra.signal] : [])]),
                 });
                 const data = await response.json();

package/dist/asset-production-tools.js

@@ -47,7 +47,7 @@ export function registerAssetProductionTools(register, options, schema = z) {
     }));
     register('gripforge_asset_search', {
         title: 'Search workspace and Community assets',
-        description: 'Search actual asset models, materials and animations, independently of Game Kit modules. Returns provenance, import requirements and Library ids. Results are ranked best first by fitness for a GripForge game (score/100, grade A–D, reasons: triangle budget for the target, rigged and clean rig, clips, empty-handed characters, attachable weapons, classified, file size, adoption); `best` is the top pick across sources. Prefer grade A/B; read the reasons before choosing a C/D. Search both sources before manufacturing missing roles. An empty kit search does not mean there are no assets. Search is free; never substitutes proxy geometry for finished models.',
+        description: 'Search actual asset models, materials and animations, independently of Game Kit modules. Returns provenance, import requirements and Library ids. Results are ranked best first by fitness for a GripForge game (score/100, grade A–D, reasons: triangle budget for the target, rigged and clean rig, clips, empty-handed characters, attachable weapons, classified, file size, adoption); `best` is the top pick across sources. Prefer grade A/B; read the reasons before choosing a C/D. Search both sources before manufacturing missing roles. An empty kit search does not mean there are no assets. Search is free; never substitutes proxy geometry for finished models. In a Game Kit project, use it to fill what gripforge_game_audit reports missing (a creature slot gets ranked proposals from gripforge_gamekit_creatures; a character without clips is animated, not left idle).',
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             q: schema.string().max(200).describe('Visual role or style, e.g. sci-fi turret, rock, soldier.'),

package/dist/game-creation-tools.js

@@ -13,7 +13,7 @@ export function registerGameCreationTools(register, options, schema = z) {
     };
     register(GAME_CREATION_TOOL_NAMES[0], {
         title: 'Prepare and resume a game',
-        description: 'The website and CLI share this saved 3D game creation workflow. Ask which engine (Unity, Godot, Unreal, Three.js) if unspecified; do not choose silently. create saves a brief without spending. quote(operation=plan) estimates AI preparation, accept(quote_token) starts its durable job ONLY after user approval of the shown price. get returns a persistent operation log, slots, studio_url and the same project to resume. Planning can select an appropriate preset OR compose real engine-compatible modules. A missing preset never means the genre needs a native engine. composition.modules pins all module versions; composition.tasks lists the custom logic still to implement. Assembly is a foundation, not a completed custom game: use the coding agent to finish those tasks on the selected engine (including web/Three.js). quote refine with message updates the same plan after approval, preserves selected assets and reviewed work, and persists the conversation. use_reference with slot_id and an owned image asset_id supplies an uploaded concept for visual review. assets searches compatible workspace/community items ranked by the brief and role; select chooses one or sets mode=generate with a prompt. For generation: quote concept, obtain approval, accept, poll get, show the concept, approve_concept only after visual user review; quote generate, obtain approval, accept, poll, show the model in its studio, approve_asset only after visual review. Never infer visual approval from technical success. quote build then accept acquires the selected community assets and binds them to a Game Kit prototype, without generating extra assets. With explicit allow_incomplete=true on the build quote, unreviewed models are excluded and missing slots use module defaults where available or remain empty. Show missing_assets before approval; never imply that an incomplete prototype is finished. Native engine projects still need CLI delivery/import; a web project has a play_url. Revision required for edits. Cancel/retry preserve completed steps. 2D unsupported. No automatic spending, invented asset IDs, or unrelated template substitutions.',
+        description: 'The website and CLI share this saved 3D game creation workflow. Ask which engine (Unity, Godot, Unreal, Three.js) if unspecified; do not choose silently. create saves a brief without spending. quote(operation=plan) estimates AI preparation, accept(quote_token) starts its durable job ONLY after user approval of the shown price. get returns a persistent operation log, slots, studio_url and the same project to resume. Planning can select an appropriate preset OR compose real engine-compatible modules. A missing preset never means the genre needs a native engine. composition.modules pins all module versions; composition.tasks lists the custom logic still to implement. Assembly is a foundation, not a completed custom game: use the coding agent to finish those tasks on the selected engine (including web/Three.js). After a build, get also returns creatures (the models bound so that no unit is a capsule) and audit { verdict: complete | playable_with_defects | incomplete, headline, fixed (the free fixes applied: models, standard clips, control scheme), defects [{ severity, message, fix { tool, args, credits? } }], next }: show the user the verdict and what is left, work through next (gripforge_game_audit reads it again), and never present a verdict other than complete as a finished game. quote refine with message updates the same plan after approval, preserves selected assets and reviewed work, and persists the conversation. use_reference with slot_id and an owned image asset_id supplies an uploaded concept for visual review. assets searches compatible workspace/community items ranked by the brief and role; select chooses one or sets mode=generate with a prompt. For generation: quote concept, obtain approval, accept, poll get, show the concept, approve_concept only after visual user review; quote generate, obtain approval, accept, poll, show the model in its studio, approve_asset only after visual review. Never infer visual approval from technical success. quote build then accept acquires the selected community assets and binds them to a Game Kit prototype, without generating extra assets. With explicit allow_incomplete=true on the build quote, unreviewed models are excluded and missing slots use module defaults where available or remain empty. Show missing_assets before approval; never imply that an incomplete prototype is finished. Native engine projects still need CLI delivery/import; a web project has a play_url. Revision required for edits. Cancel/retry preserve completed steps. 2D unsupported. No automatic spending, invented asset IDs, or unrelated template substitutions.',
         inputSchema: shape, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async (args, extra) => {
         const parsed = schema.object(shape).strict().safeParse(args);

package/dist/game-import-agent.js

@@ -0,0 +1,457 @@
+import { constants } from 'node:fs';
+import { readdir, mkdir, readFile, writeFile, rename, realpath, stat, open, access, unlink } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { normalizedPath } from './game-import-normalize.js';
+const MAX_FILES = 20000, MAX_BYTES = 256 * 1024 * 1024, MAX_JSON = 8 * 1024 * 1024;
+const OMIT = new Set(['.git', '.svn', 'node_modules', '.env', '.aws', '.ssh', 'Library', 'Temp', 'Logs', 'obj', '.DS_Store']);
+export const importHome = () => process.env.GRIPFORGE_GAME_IMPORT_HOME || join(homedir(), '.gripforge', 'game-imports');
+export function jobDirectory(id) {
+    if (!/^gi_[a-f0-9]{24}$/.test(id))
+        throw Error('Invalid import id');
+    return join(importHome(), id);
+}
+export async function loadImportJob(id) { return JSON.parse(await readFile(join(jobDirectory(id), 'job.json'), 'utf8')); }
+export async function saveImportJob(job) {
+    const dir = jobDirectory(job.id);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    job.updatedAt = new Date().toISOString();
+    const tmp = join(dir, `job.${process.pid}.tmp`);
+    await writeFile(tmp, JSON.stringify(job, null, 2), { mode: 0o600 });
+    await rename(tmp, join(dir, 'job.json'));
+    if (job.report) {
+        const report = join(dir, `report.${process.pid}.tmp`);
+        await writeFile(report, JSON.stringify(job.report, null, 2), { mode: 0o600 });
+        await rename(report, join(dir, 'report.json'));
+    }
+}
+export async function newImportJob(path) {
+    if (!isAbsolute(path))
+        throw Error('Use an absolute local directory path');
+    const root = await realpath(path);
+    if (!(await stat(root)).isDirectory())
+        throw Error('Source must be a directory');
+    if (root === sep || root === homedir())
+        throw Error('Select the game/project directory, not the whole computer');
+    const job = { schema: 'gripforge.game-import-job.v1', id: `gi_${randomBytes(12).toString('hex')}`, root, phase: 'analyze', status: 'queued', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), completed: 0, total: 0, receipts: {}, errors: {} };
+    await saveImportJob(job);
+    return job;
+}
+export async function confinedFile(root, path) {
+    if (!path || isAbsolute(path) || path.split(/[\\/]/).includes('..'))
+        throw Error('Unsafe source reference');
+    const requested = resolve(root, path), actual = await realpath(requested);
+    if (actual !== requested || !actual.startsWith(root + sep))
+        throw Error('Symlink or external source reference rejected');
+    const info = await stat(actual);
+    if (!info.isFile() || info.size > MAX_BYTES)
+        throw Error('File unavailable or exceeds 256 MiB');
+    return actual;
+}
+async function readSource(root, path) {
+    const file = await confinedFile(root, path), handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    try {
+        const s = await handle.stat();
+        if (s.size > MAX_BYTES)
+            throw Error('File exceeds 256 MiB');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+const digest = (data) => createHash('sha256').update(data).digest('hex');
+const media = new Set(['.png', '.jpg', '.jpeg', '.webp', '.wav', '.ogg', '.mp3']);
+const structured = new Set(['.prefab', '.unity', '.mat', '.asset', '.anim', '.meta', '.cs', '.tscn', '.tres', '.uproject', '.uasset', '.umap', '.pak', '.utoc', '.ucas', '.dll', '.bundle', '.assets', '.fbx', '.obj', '.glb', '.gltf', '.dds', '.tga', '.shader', '.vfx']);
+const nameRules = [
+    [/(^|[\W_])(sword|longsword|katana|axe|rifle|ak47|pistol|shotgun|weapon)([\W_]|$)/i, 'weapon'],
+    [/(^|[\W_])(building|house|warehouse|tower)([\W_]|$)/i, 'building'],
+    [/(^|[\W_])(vehicle|car|truck|kart)([\W_]|$)/i, 'vehicle'],
+    [/(^|[\W_])(character|soldier|hero|npc|enemy)([\W_]|$)/i, 'character'],
+    [/(^|[\W_])(terrain|landscape|environment)([\W_]|$)/i, 'environment'],
+];
+function gltfJSON(bytes, ext) {
+    if (ext === '.gltf') {
+        if (bytes.length > MAX_JSON)
+            throw Error('glTF JSON exceeds limit');
+        return JSON.parse(bytes.toString());
+    }
+    if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 || bytes.readUInt32LE(4) !== 2 || bytes.readUInt32LE(8) !== bytes.length || bytes.readUInt32LE(16) !== 0x4e4f534a)
+        throw Error('Invalid GLB header');
+    const len = bytes.readUInt32LE(12);
+    if (len > MAX_JSON || 20 + len > bytes.length)
+        throw Error('Invalid GLB JSON length');
+    return JSON.parse(bytes.subarray(20, 20 + len).toString());
+}
+export function inspectAsset(path, bytes) {
+    const ext = extname(path).toLowerCase(), sha256 = digest(bytes), evidence = [];
+    const a = { id: `src_${digest(path).slice(0, 24)}`, path, name: basename(path, ext), format: ext.slice(1), bytes: bytes.length, sha256, kind: 'unknown', evidence, status: 'blocked', details: {}, suggestedKits: [] };
+    if (['.glb', '.gltf', '.fbx', '.obj'].includes(ext)) {
+        a.kind = 'prop';
+        const rule = nameRules.find(([r]) => r.test(path));
+        evidence.push({ source: path, reason: 'Mesh file format; role needs review', confidence: .4 });
+        if (rule) {
+            a.kind = rule[1];
+            evidence.push({ source: path, reason: 'Role suggested by filename, not verified visually', confidence: .55 });
+        }
+        if (ext === '.glb' || ext === '.gltf') {
+            try {
+                const doc = gltfJSON(bytes, ext);
+                if (doc.asset?.version !== '2.0')
+                    throw Error('Requires glTF 2');
+                a.details.meshes = doc.meshes?.length ?? 0;
+                a.details.materials = (doc.materials ?? []).map((m, i) => String(m.name ?? `material_${i}`));
+                a.details.clips = (doc.animations ?? []).map((m, i) => String(m.name ?? `clip_${i}`));
+                a.details.joints = [...new Set((doc.skins ?? []).flatMap((s) => (s.joints ?? []).map((i) => String(doc.nodes?.[i]?.name ?? `joint_${i}`))))];
+                if (a.details.joints.length) {
+                    a.details.rig = 'unclassified';
+                    evidence.push({ source: path, reason: 'glTF skin joints found; anatomy/retargeting not validated', confidence: 1 });
+                }
+                if (!a.details.meshes && a.details.clips?.length)
+                    a.kind = 'animation';
+                a.details.dependencies = [...(doc.buffers ?? []), ...(doc.images ?? [])].map((b) => b.uri).filter((s) => typeof s === 'string' && !s.startsWith('data:'));
+                a.status = ext === '.glb' && !a.details.dependencies.length ? 'ready' : 'convertible';
+                if (ext === '.glb' && a.details.dependencies.length) {
+                    a.status = 'blocked';
+                    a.reason = 'GLB references external resources; export a self-contained GLB';
+                }
+            }
+            catch (e) {
+                a.reason = String(e);
+            }
+        }
+        else
+            a.reason = 'Export to GLB with Blender or the source editor before import';
+    }
+    else if (media.has(ext)) {
+        const valid = ext === '.png' ? bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) : ['.jpg', '.jpeg'].includes(ext) ? bytes[0] === 255 && bytes[1] === 216 : ext === '.webp' ? bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP' : ext === '.wav' ? bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WAVE' : ext === '.ogg' ? bytes.toString('ascii', 0, 4) === 'OggS' : bytes.toString('ascii', 0, 3) === 'ID3' || bytes[0] === 255 && (bytes[1] & 0xe0) === 0xe0;
+        a.kind = ['.wav', '.ogg', '.mp3'].includes(ext) ? 'audio' : 'texture';
+        a.status = valid ? 'ready' : 'blocked';
+        if (!valid)
+            a.reason = 'File signature does not match extension';
+        evidence.push({ source: path, reason: valid ? 'Media signature verified' : 'Invalid media signature', confidence: 1 });
+    }
+    else {
+        const kind = { '.prefab': 'scene', '.unity': 'scene', '.umap': 'scene', '.tscn': 'scene', '.mat': 'material', '.anim': 'animation', '.cs': 'script', '.dll': 'script', '.shader': 'script', '.vfx': 'vfx', '.pak': 'container', '.utoc': 'container', '.ucas': 'container', '.assets': 'container', '.bundle': 'container' };
+        a.kind = kind[ext] ?? 'unknown';
+        a.reason = 'Requires an engine exporter or format-specific converter';
+    }
+    if (a.kind === 'weapon')
+        a.suggestedKits = ['weapons.loadout', 'combat.melee', 'combat.projectiles'];
+    if (a.kind === 'vehicle')
+        a.suggestedKits = ['vehicle.driveable', 'vehicle.enter_exit'];
+    return a;
+}
+/** Local orchestration, not a renderer. Source files are never executed or modified. */
+export class GameImportAgent {
+    job;
+    constructor(job) {
+        this.job = job;
+    }
+    async cancelled() { try {
+        await access(join(jobDirectory(this.job.id), 'cancel'));
+        return true;
+    }
+    catch {
+        return false;
+    } }
+    async checkpoint() { if (await this.cancelled()) {
+        this.job.status = 'cancelled';
+        await saveImportJob(this.job);
+        throw Error('Import cancelled');
+    } await saveImportJob(this.job); }
+    async discover_assets() {
+        const files = [], warnings = [], home = await realpath(importHome()), skipHome = !this.job.root.startsWith(home + sep);
+        const walk = async (dir, depth) => {
+            if (depth > 32) {
+                warnings.push(`Depth limit: ${relative(this.job.root, dir)}`);
+                return;
+            }
+            if (await this.cancelled())
+                throw Error('Import cancelled');
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const e of entries) {
+                if (OMIT.has(e.name) || e.name.startsWith('.env') || e.name.startsWith('.'))
+                    continue;
+                const p = join(dir, e.name);
+                if (skipHome && (p === home || p.startsWith(home + sep)))
+                    continue;
+                if (e.isSymbolicLink()) {
+                    warnings.push(`Skipped symlink: ${relative(this.job.root, p)}`);
+                    continue;
+                }
+                if (e.isDirectory())
+                    await walk(p, depth + 1);
+                else if (e.isFile()) {
+                    if (files.length >= MAX_FILES)
+                        throw Error('Scan exceeds 20,000 files; select a smaller source directory');
+                    files.push(relative(this.job.root, p).split(sep).join('/'));
+                }
+            }
+        };
+        await walk(this.job.root, 0);
+        return { files: files.sort(), warnings };
+    }
+    async detect_engine(files) {
+        const has = (r) => files.find(p => r.test(p));
+        const unity = has(/(?:UnityPlayer\.(?:dll|so|dylib)|global-metadata\.dat|ProjectSettings\/ProjectVersion\.txt|(?:^|\/)[^/]+_Data\/)/i);
+        const unreal = has(/\.uproject$|\.utoc$|(?:^|\/)Content\/Paks\//i);
+        const godot = has(/(?:^|\/)project\.godot$|\.pck$/i);
+        const web = has(/(?:^|\/)package\.json$/i);
+        const name = unity ? 'unity' : unreal ? 'unreal' : godot ? 'godot' : web ? 'web' : 'unknown';
+        const evidence = [{ source: unity ?? unreal ?? godot ?? web ?? '.', reason: name === 'unknown' ? 'No recognized engine marker; do not infer native engine from absence' : 'Engine filesystem marker', confidence: name === 'unknown' ? 0 : web ? .4 : .95 }];
+        let version;
+        const vf = has(/ProjectSettings\/ProjectVersion\.txt$/i);
+        if (vf)
+            version = (await readSource(this.job.root, vf)).toString().match(/m_EditorVersion:\s*(\S+)/)?.[1];
+        const uf = has(/\.uproject$/i);
+        if (uf) {
+            try {
+                version = JSON.parse((await readSource(this.job.root, uf)).toString()).EngineAssociation;
+            }
+            catch { }
+        }
+        return { name, version, runtime: name === 'unity' ? has(/global-metadata\.dat$|GameAssembly\.dll$/i) ? 'IL2CPP' : has(/Managed\/Assembly-CSharp\.dll$/i) ? 'Mono' : 'unknown' : name === 'unreal' ? 'native' : name === 'godot' ? 'GDScript / native (unverified)' : 'unknown', evidence };
+    }
+    select_toolchain(engine) {
+        const steps = [{ tool: 'GripForge file importer', purpose: 'Inspect GLB, pack glTF, index images/audio and Unity GUID references', status: 'builtin', reason: 'Known portable formats first' }];
+        if (engine.name === 'unity') {
+            steps.push({ tool: 'AssetRipper', purpose: 'Export Unity assets through an installed local AssetRipper HTTP instance, then rescan', status: 'external', reason: 'Set GRIPFORGE_ASSETRIPPER_URL to a dedicated loopback instance; external GPL tool, not bundled' });
+            steps.push({ tool: 'AssetStudio', purpose: 'Alternative asset exploration/export', status: 'manual', reason: 'Archived original repository; use only for compatible builds' });
+            if (engine.runtime === 'IL2CPP')
+                steps.push({ tool: 'Cpp2IL', purpose: 'Recover classes and metadata, not meshes', status: 'external', reason: 'Run an installed version with its documented options in an isolated output directory' });
+            else if (engine.runtime === 'Mono')
+                steps.push({ tool: 'ILSpy', purpose: 'Inspect managed controllers; code stays local', status: 'external', reason: 'Optional installed ilspycmd; does not export meshes' });
+        }
+        else if (engine.name === 'unreal')
+            steps.push({ tool: 'Unreal editor / GripForge Unreal export', purpose: 'Export an owned project through the existing Unreal scene pipeline', status: 'external', reason: 'Native project path supported; cooked packages require compatible extractor, not direct GLB import' });
+        else if (engine.name === 'godot')
+            steps.push({ tool: 'Godot editor', purpose: 'Export source scenes/meshes and inspect resources', status: 'manual', reason: 'PCK archives are indexed, not unpacked by this version' });
+        steps.push({ tool: 'Blender', purpose: 'Normalize extracted FBX/OBJ/DDS/TGA through a durable local manufacture worker', status: 'external', reason: 'Configure GRIPFORGE_BLENDER_BIN; preserves available embedded materials/rig/clips, missing resources require a self-contained source export' });
+        if (engine.name === 'unknown')
+            steps.push({ tool: 'Ghidra MCP / REA', purpose: 'Investigate unknown formats and document a converter', status: 'external', reason: 'Configure GRIPFORGE_GHIDRA_MCP_URL; use the bounded gripforge_reverse_* abstraction. Fallback only. Analysis is not an asset conversion; no untrusted game code is launched' });
+        return steps;
+    }
+    async analyze_asset_relationships(report) {
+        const guids = new Map();
+        for (const a of report.assets) {
+            try {
+                const meta = (await readSource(this.job.root, a.path + '.meta')).toString();
+                const guid = meta.match(/^guid:\s*([a-f0-9]{32})/m)?.[1];
+                if (guid) {
+                    a.details.guid = guid;
+                    if (guids.has(guid))
+                        report.warnings.push(`Duplicate Unity GUID: ${guid}`);
+                    else
+                        guids.set(guid, a.id);
+                }
+            }
+            catch { }
+        }
+        for (const a of report.assets) {
+            if (!['prefab', 'unity', 'mat', 'asset', 'anim'].includes(a.format) || a.bytes > MAX_JSON)
+                continue;
+            const text = (await readSource(this.job.root, a.path)).toString();
+            for (const guid of new Set([...text.matchAll(/guid:\s*([a-f0-9]{32})/g)].map(m => m[1]))) {
+                const to = guids.get(guid);
+                if (to && to !== a.id)
+                    report.relationships.push({ from: a.id, to, type: 'references', evidence: { source: a.path, reason: `Serialized Unity GUID reference ${guid}`, confidence: 1 } });
+            }
+        }
+    }
+    async analyze() {
+        const { files, warnings } = await this.discover_assets(), engine = await this.detect_engine(files);
+        const candidates = files.filter(p => media.has(extname(p).toLowerCase()) || structured.has(extname(p).toLowerCase())).filter(p => !p.endsWith('.meta'));
+        const report = { schema: 'gripforge.game-import.v1', id: this.job.id, source: basename(this.job.root), createdAt: this.job.createdAt, engine, assets: [], relationships: [], counts: {}, warnings, toolchain: this.select_toolchain(engine), normalization: { supported: ['Self-contained GLB preserving PBR/skins/clips', 'glTF 2 with embedded local buffers/images → GLB', 'PNG/JPEG/WebP and WAV/OGG/MP3', 'Installed Blender FBX/OBJ → GLB and DDS/TGA → PNG with persistent provenance'], requiresReview: ['Semantic kind/subtype', 'Skeleton anatomy and retargeting', 'PBR reconstruction for legacy formats', 'LOD and colliders', 'Sockets and Game Kit behavior mapping', 'GripForge renderer visual review before promotion'] } };
+        const previous = new Map(this.job.report?.assets.map(a => [a.path, a]) ?? []);
+        this.job.report = report;
+        this.job.total = candidates.length;
+        this.job.completed = 0;
+        for (const p of candidates) {
+            try {
+                const bytes = await readSource(this.job.root, p);
+                const old = previous.get(p);
+                const a = old?.sha256 === digest(bytes) ? old : inspectAsset(p, bytes);
+                if (a.format === 'gltf' && a.status === 'convertible') {
+                    a.details.resources = {};
+                    try {
+                        for (const uri of a.details.dependencies ?? []) {
+                            if (/^[a-z]+:/i.test(uri) || uri.startsWith('/') || uri.includes('\\'))
+                                throw Error('External resource URI rejected');
+                            const ref = relative(this.job.root, resolve(this.job.root, dirname(p), decodeURIComponent(uri)));
+                            a.details.resources[ref] = digest(await readSource(this.job.root, ref));
+                        }
+                    }
+                    catch (e) {
+                        a.status = 'blocked';
+                        a.reason = String(e);
+                    }
+                }
+                report.assets.push(a);
+            }
+            catch (e) {
+                report.warnings.push(`${p}: ${String(e)}`);
+            }
+            this.job.completed++;
+            if (this.job.completed % 10 === 0)
+                await this.checkpoint();
+        }
+        await this.analyze_asset_relationships(report);
+        for (const a of report.assets)
+            report.counts[a.kind] = (report.counts[a.kind] ?? 0) + 1;
+        this.job.status = 'awaiting_selection';
+        await this.checkpoint();
+        return report;
+    }
+    async normalize_assets(a) {
+        const bytes = await readSource(this.job.root, a.path);
+        if (digest(bytes) !== a.sha256)
+            throw Error('Source changed after analysis; analyze again');
+        if (a.details.normalization) {
+            const n = a.details.normalization;
+            const output = await readFile(normalizedPath(this.job, a.id, n.format));
+            if (n.sourceSha256 !== a.sha256 || digest(output) !== n.sha256)
+                throw Error('Normalized checkpoint changed; normalize again');
+            return { bytes: output, filename: basename(a.path, extname(a.path)) + '.' + n.format };
+        }
+        if (a.status === 'blocked')
+            throw Error(a.reason ?? 'Extraction/conversion required');
+        if (a.format !== 'gltf')
+            return { bytes, filename: basename(a.path) };
+        const doc = gltfJSON(bytes, '.gltf'), chunks = [], offsets = [];
+        let total = 0;
+        if (doc.extensionsUsed?.includes('EXT_meshopt_compression'))
+            throw Error('meshopt-compressed glTF requires decompression before packing');
+        const append = (b) => { const offset = total; chunks.push(b); total += b.length; const pad = (4 - total % 4) % 4; if (pad) {
+            chunks.push(Buffer.alloc(pad));
+            total += pad;
+        } if (total > MAX_BYTES)
+            throw Error('Packed glTF exceeds 256 MiB'); return offset; };
+        const resource = async (uri) => {
+            if (typeof uri !== 'string')
+                throw Error('Missing glTF resource URI');
+            if (uri.startsWith('data:')) {
+                const m = uri.match(/^data:[^;,]+;base64,([a-zA-Z0-9+/=\s]+)$/);
+                if (!m)
+                    throw Error('Unsupported data URI');
+                return Buffer.from(m[1], 'base64');
+            }
+            if (/^[a-z]+:/i.test(uri) || uri.startsWith('/') || uri.includes('\\'))
+                throw Error('Remote/absolute glTF resources are forbidden');
+            // ../ within the selected root is allowed for ordinary exporter layouts; never outside it.
+            const p = relative(this.job.root, resolve(this.job.root, dirname(a.path), decodeURIComponent(uri)));
+            const data = await readSource(this.job.root, p);
+            if (a.details.resources?.[p] !== digest(data))
+                throw Error('glTF dependency changed after analysis; analyze again');
+            return data;
+        };
+        for (const b of doc.buffers ?? []) {
+            const content = await resource(b.uri);
+            if (content.length < b.byteLength)
+                throw Error('Truncated glTF buffer');
+            offsets.push(append(content));
+        }
+        for (const v of doc.bufferViews ?? []) {
+            if (offsets[v.buffer] === undefined)
+                throw Error('Invalid glTF buffer binding');
+            v.byteOffset = (v.byteOffset ?? 0) + offsets[v.buffer];
+            v.buffer = 0;
+        }
+        for (const image of doc.images ?? [])
+            if (image.uri) {
+                const uri = image.uri, content = await resource(uri), mime = uri.startsWith('data:') ? uri.slice(5, uri.indexOf(';')) : /\.png$/i.test(uri) ? 'image/png' : /\.webp$/i.test(uri) ? 'image/webp' : /\.jpe?g$/i.test(uri) ? 'image/jpeg' : null;
+                if (!mime)
+                    throw Error('Image requires PNG/JPEG/WebP conversion');
+                doc.bufferViews ??= [];
+                image.bufferView = doc.bufferViews.length;
+                image.mimeType = mime;
+                doc.bufferViews.push({ buffer: 0, byteOffset: append(content), byteLength: content.length });
+                delete image.uri;
+            }
+        doc.buffers = [{ byteLength: total }];
+        const json = Buffer.from(JSON.stringify(doc)), padded = Buffer.concat([json, Buffer.alloc((4 - json.length % 4) % 4, 32)]), binary = Buffer.concat(chunks);
+        const header = Buffer.alloc(20);
+        header.writeUInt32LE(0x46546c67);
+        header.writeUInt32LE(2, 4);
+        header.writeUInt32LE(28 + padded.length + binary.length, 8);
+        header.writeUInt32LE(padded.length, 12);
+        header.writeUInt32LE(0x4e4f534a, 16);
+        const bh = Buffer.alloc(8);
+        bh.writeUInt32LE(binary.length);
+        bh.writeUInt32LE(0x004e4942, 4);
+        return { bytes: Buffer.concat([header, padded, bh, binary]), filename: basename(a.path, '.gltf') + '.glb' };
+    }
+    async import_to_gripforge(key) {
+        const job = this.job;
+        if (!job.report || !job.rights || !job.origin || !job.workspace || !job.selected?.length)
+            throw Error('Analysis, selection, workspace and rights basis required');
+        const headers = { 'x-api-key': key, 'x-workspace-id': job.workspace, 'x-gripforge-client': 'mcp' };
+        const request = async (body, json = false) => {
+            for (let attempt = 0; attempt < 6; attempt++) {
+                if (await this.cancelled())
+                    throw Error('Import cancelled');
+                const res = await fetch(job.origin + '/api/v1/game-imports', { method: 'POST', headers: { ...headers, ...(json ? { 'content-type': 'application/json' } : {}) }, body, signal: AbortSignal.timeout(120000) });
+                const result = await res.json();
+                if (res.status === 503 && result.code === 'import_busy' && attempt < 5) {
+                    await new Promise(r => setTimeout(r, Math.min(5000, 1000 * (attempt + 1))));
+                    continue;
+                }
+                if (!res.ok)
+                    throw Error(String(result.error ?? `HTTP ${res.status}`));
+                return result;
+            }
+            throw Error('Import persistence lane unavailable; resume later');
+        };
+        await request(JSON.stringify({ report: job.report, rights: job.rights }), true);
+        job.total = job.selected.length;
+        job.completed = job.selected.filter(id => job.receipts[id]).length;
+        await this.checkpoint();
+        for (const id of job.selected) {
+            if (job.receipts[id])
+                continue;
+            await this.checkpoint();
+            const a = job.report.assets.find(a => a.id === id);
+            if (!a)
+                throw Error('Selected asset not in inventory');
+            try {
+                const output = await this.normalize_assets(a), form = new FormData();
+                form.set('job_id', job.id);
+                form.set('asset_id', a.id);
+                form.set('file', new Blob([new Uint8Array(output.bytes)]), output.filename);
+                const result = await request(form);
+                job.receipts[id] = { itemId: result.item.id, revision: result.revision?.revisionId, studioUrl: result.studio_url };
+                delete job.errors[id];
+                job.completed++;
+            }
+            catch (e) {
+                job.errors[id] = e instanceof Error ? e.message : String(e);
+            }
+            await this.checkpoint();
+        }
+        job.status = job.selected.some(id => !job.receipts[id]) ? 'failed' : 'completed';
+        await this.checkpoint();
+    }
+}
+/** Exclusive per-job worker lease. Dead workers can be resumed without discarding receipts. */
+export async function claimImportJob(id) {
+    const lock = join(jobDirectory(id), 'worker.lock');
+    try {
+        const old = Number(await readFile(lock, 'utf8'));
+        try {
+            process.kill(old, 0);
+            throw Error('A worker is already running for this import');
+        }
+        catch (e) {
+            if (e.code !== 'ESRCH')
+                throw e;
+        }
+        await unlink(lock);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await writeFile(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+    return async () => { await unlink(lock).catch(() => { }); };
+}