refactor: 拆分 agent_loop.py 为 agent_core 包与 cli 入口

- 将主循环与工具调度抽到 agent_core.agent
- 常量与客户端工厂抽到 agent_core.config
- SYSTEM prompt 抽到 agent_core.prompts
- run_dir/manifest 相关抽到 agent_core.outputs
- 通用 json_response/tail_text 抽到 agent_core.utils
- CadQuery 与 Lux3D 工具分别放到 agent_core.tools.{cadquery_tool,lux3d_tool}
- 新增 cli.py 作为终端入口
- agent_loop.py 保留为向后兼容壳，维持 python agent_loop.py 可用

agent_core/__init__.py

@@ -0,0 +1,2 @@
+"""Core package for the CAD and 3D generation agent."""
+

agent_core/agent.py

@@ -0,0 +1,72 @@
+from agent_core.config import DEFAULT_CADQUERY_OUTPUT_PATH, get_client, get_model_id
+from agent_core.prompts import SYSTEM
+from agent_core.tools.cadquery_tool import TOOL_SCHEMA as CADQUERY_TOOL_SCHEMA
+from agent_core.tools.cadquery_tool import run_execute_cadquery
+from agent_core.tools.lux3d_tool import TOOL_SCHEMA as LUX3D_TOOL_SCHEMA
+from agent_core.tools.lux3d_tool import run_generate_3d_model
+
+
+TOOL_HANDLERS = {
+    "execute_cadquery": lambda **kw: run_execute_cadquery(
+        kw["code"],
+        kw.get("output_path", DEFAULT_CADQUERY_OUTPUT_PATH),
+    ),
+    "generate_3d_model": lambda **kw: run_generate_3d_model(
+        kw["image_path"],
+        kw.get("output_path"),
+    ),
+}
+
+TOOLS = [
+    CADQUERY_TOOL_SCHEMA,
+    LUX3D_TOOL_SCHEMA,
+]
+
+
+def latest_user_prompt(messages: list) -> str | None:
+    for message in reversed(messages):
+        if message.get("role") == "user" and isinstance(message.get("content"), str):
+            return message["content"]
+    return None
+
+
+def agent_loop(messages: list):
+    client = get_client()
+    model = get_model_id()
+
+    while True:
+        response = client.messages.create(
+            model=model,
+            system=SYSTEM,
+            messages=messages,
+            tools=TOOLS,
+            max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        prompt = latest_user_prompt(messages)
+        for block in response.content:
+            if block.type == "tool_use":
+                if block.name == "execute_cadquery":
+                    output = run_execute_cadquery(
+                        code=block.input["code"],
+                        output_path=block.input.get("output_path", DEFAULT_CADQUERY_OUTPUT_PATH),
+                        prompt=prompt,
+                    )
+                elif block.name == "generate_3d_model":
+                    output = run_generate_3d_model(
+                        image_path=block.input["image_path"],
+                        output_path=block.input.get("output_path"),
+                        prompt=prompt,
+                    )
+                else:
+                    handler = TOOL_HANDLERS.get(block.name)
+                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
+
+                print(f"> {block.name}: {output[:200]}")
+                results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
+        messages.append({"role": "user", "content": results})
+

agent_core/config.py

@@ -0,0 +1,38 @@
+import os
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    def load_dotenv(*args, **kwargs):
+        return False
+
+
+load_dotenv(override=True)
+
+if os.getenv("ANTHROPIC_BASE_URL"):
+    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
+
+
+WORKDIR = Path.cwd()
+DEFAULT_CADQUERY_OUTPUT_PATH = "outputs/model.step"
+DEFAULT_LUX3D_OUTPUT_PATH = "outputs"
+STEP_SUFFIXES = (".step", ".stp")
+IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp")
+
+LUX3D_API_KEY_ENV = "LUX3D_API_KEY"
+LUX3D_CREATE_URL = "https://api.luxreal.ai/global/lux3d/generate/task/create"
+LUX3D_GET_URL = "https://api.luxreal.ai/global/lux3d/generate/task/get"
+LUX3D_POLL_INTERVAL_SECONDS = 12
+LUX3D_TIMEOUT_SECONDS = 600
+
+
+def get_client():
+    from anthropic import Anthropic
+
+    return Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
+
+
+def get_model_id() -> str:
+    return os.environ["MODEL_ID"]
+

agent_core/outputs.py

@@ -0,0 +1,138 @@
+import json
+from datetime import datetime
+from pathlib import Path
+from uuid import uuid4
+
+from agent_core.config import DEFAULT_LUX3D_OUTPUT_PATH, STEP_SUFFIXES, WORKDIR
+
+
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+
+def workspace_relative(path: Path) -> str:
+    return str(path.relative_to(WORKDIR))
+
+
+def new_run_id() -> str:
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return f"{timestamp}_{uuid4().hex[:6]}"
+
+
+def allocate_run_dir(output_root: Path) -> tuple[Path, str]:
+    for _ in range(20):
+        run_id = new_run_id()
+        run_dir = output_root / "runs" / run_id
+        if not run_dir.exists():
+            return run_dir, run_id
+
+    raise RuntimeError("Failed to allocate a unique output run directory.")
+
+
+def resolve_run_output(requested_output_path: str) -> tuple[Path, Path, str]:
+    requested_path = safe_path(requested_output_path)
+    suffix = requested_path.suffix.lower()
+
+    if suffix in STEP_SUFFIXES:
+        output_root = requested_path.parent
+        output_name = requested_path.name
+    elif suffix:
+        raise ValueError("Only STEP output is supported in this version. Use a .step/.stp file path or a directory path.")
+    else:
+        output_root = requested_path
+        output_name = "model.step"
+
+    run_dir, run_id = allocate_run_dir(output_root)
+    return run_dir, run_dir / output_name, run_id
+
+
+def resolve_lux3d_run(output_path: str | None) -> tuple[Path, Path, str, str | None, str]:
+    requested_output_path = output_path or DEFAULT_LUX3D_OUTPUT_PATH
+    requested_path = safe_path(requested_output_path)
+    if requested_path.suffix:
+        output_root = requested_path.parent
+        output_name = requested_path.name
+    else:
+        output_root = requested_path
+        output_name = None
+
+    run_dir, run_id = allocate_run_dir(output_root)
+    return output_root, run_dir, run_id, output_name, requested_output_path
+
+
+def update_latest_link(output_root: Path, run_dir: Path) -> str | None:
+    latest = output_root / "latest"
+    try:
+        if latest.is_symlink() or latest.is_file():
+            latest.unlink()
+        elif latest.exists():
+            return f"Skipped latest link because {workspace_relative(latest)} already exists and is not a symlink."
+
+        latest.symlink_to(Path("runs") / run_dir.name, target_is_directory=True)
+    except OSError as exc:
+        return f"Failed to update latest link: {exc}"
+
+    return None
+
+
+def write_manifest(
+    run_dir: Path,
+    run_id: str,
+    requested_output_path: str,
+    output_path: Path,
+    code: str,
+    prompt: str | None,
+    payload: dict,
+) -> Path:
+    manifest_path = run_dir / "manifest.json"
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest = {
+        "run_id": run_id,
+        "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "prompt": prompt,
+        "requested_output_path": requested_output_path,
+        "output_path": workspace_relative(output_path),
+        "format": output_path.suffix.lstrip(".").lower(),
+        "code": code,
+        "stdout": payload.get("stdout", ""),
+        "stderr": payload.get("stderr", ""),
+    }
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    return manifest_path
+
+
+def write_lux3d_manifest(
+    run_dir: Path,
+    run_id: str,
+    prompt: str | None,
+    image_path: Path,
+    requested_output_path: str,
+    output_path: Path | None,
+    busid: str | int | None,
+    status: int | None,
+    result_url: str | None,
+    poll_count: int,
+    error: str | None = None,
+) -> Path:
+    manifest_path = run_dir / "manifest.json"
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest = {
+        "run_id": run_id,
+        "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "generator": "lux3d",
+        "prompt": prompt,
+        "image_path": workspace_relative(image_path),
+        "requested_output_path": requested_output_path,
+        "output_path": workspace_relative(output_path) if output_path else None,
+        "busid": busid,
+        "status": status,
+        "result_url": result_url,
+        "poll_count": poll_count,
+        "error": error,
+    }
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    return manifest_path
+

agent_core/prompts.py

@@ -0,0 +1,29 @@
+from agent_core.config import WORKDIR
+
+
+SYSTEM = f"""
+You are a CAD and 3D model generation agent at {WORKDIR}.
+
+You have two tools:
+- execute_cadquery: use it for precise CAD, dimensioned parts, parametric geometry, engineering models, and STEP/CAD output.
+- generate_3d_model: use it when the user provides an image path and asks for a 3D model, mesh, GLB, OBJ, or other non-precise 3D asset.
+
+For CadQuery tasks:
+- Write CadQuery Python code.
+- The code must assign the final model to a variable named result.
+- You may use cadquery as cq; it is pre-imported by the tool.
+- Call execute_cadquery with the code and optional output_path.
+- Each successful tool call writes into a unique run directory to avoid overwriting previous models.
+- If execute_cadquery returns ok=false, inspect the structured error, fix the code, and call execute_cadquery again.
+
+For image-to-3D tasks:
+- The user must provide a workspace-relative image path.
+- If the user asks for image-to-3D generation but does not provide an image path, ask for the image path. Do not guess.
+- Call generate_3d_model with the image_path and optional output_path.
+- Do not ask the user to read files, convert images to base64, call APIs, or download results manually.
+
+When a tool returns ok=true, report output_path, run_dir, and manifest_path to the user.
+
+Do not ask the user to run commands or create files manually.
+""".strip()
+

agent_core/tools/__init__.py

@@ -0,0 +1,2 @@
+"""Tool implementations for the agent runtime."""
+

agent_core/tools/cadquery_tool.py

@@ -0,0 +1,266 @@
+import json
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+from agent_core.config import DEFAULT_CADQUERY_OUTPUT_PATH, WORKDIR
+from agent_core.outputs import resolve_run_output, update_latest_link, workspace_relative, write_manifest
+from agent_core.utils import json_response
+
+
+CADQUERY_RUNNER = r"""
+import contextlib
+import io
+import json
+import sys
+import traceback
+from pathlib import Path
+
+stdout_buffer = io.StringIO()
+stderr_buffer = io.StringIO()
+
+
+def tail(text, limit=4000):
+    if not text:
+        return ""
+    return text[-limit:]
+
+
+def fail(stage, exc=None, error_type=None, error=None):
+    payload = {
+        "ok": False,
+        "stage": stage,
+        "error_type": error_type or (type(exc).__name__ if exc else "Error"),
+        "error": error or (str(exc) if exc else ""),
+        "traceback_tail": tail(traceback.format_exc() if exc else ""),
+        "stdout": tail(stdout_buffer.getvalue()),
+        "stderr": tail(stderr_buffer.getvalue()),
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+
+
+try:
+    request = json.loads(sys.stdin.read())
+    code = request["code"]
+    output_path = Path(request["output_path"])
+except Exception as exc:
+    fail("input", exc)
+    sys.exit(0)
+
+try:
+    import cadquery as cq
+except Exception as exc:
+    fail("import", exc)
+    sys.exit(0)
+
+try:
+    compiled = compile(code, "<cadquery_code>", "exec")
+except Exception as exc:
+    fail("syntax", exc)
+    sys.exit(0)
+
+namespace = {
+    "__name__": "__cadquery_user_code__",
+    "cq": cq,
+}
+
+try:
+    with contextlib.redirect_stdout(stdout_buffer), contextlib.redirect_stderr(stderr_buffer):
+        exec(compiled, namespace)
+except Exception as exc:
+    fail("execution", exc)
+    sys.exit(0)
+
+if "result" not in namespace:
+    fail("result", error_type="MissingResult", error="CadQuery code must assign the final model to variable 'result'.")
+    sys.exit(0)
+
+result = namespace["result"]
+if result is None:
+    fail("result", error_type="InvalidResult", error="'result' is None.")
+    sys.exit(0)
+
+exportable_types = tuple(
+    value
+    for name in ("Workplane", "Shape", "Assembly", "Sketch")
+    for value in [getattr(cq, name, None)]
+    if isinstance(value, type)
+)
+
+is_exportable = isinstance(result, exportable_types)
+if isinstance(result, (list, tuple)) and result:
+    is_exportable = all(isinstance(item, exportable_types) for item in result)
+
+if not is_exportable:
+    fail(
+        "result",
+        error_type="InvalidResultType",
+        error=f"'result' must be a CadQuery object or a non-empty list/tuple of CadQuery objects, got {type(result).__name__}.",
+    )
+    sys.exit(0)
+
+try:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    cq.exporters.export(result, str(output_path))
+except Exception as exc:
+    fail("export", exc)
+    sys.exit(0)
+
+payload = {
+    "ok": True,
+    "stage": "done",
+    "output_path": str(output_path),
+    "stdout": tail(stdout_buffer.getvalue()),
+    "stderr": tail(stderr_buffer.getvalue()),
+}
+print(json.dumps(payload, ensure_ascii=False))
+"""
+
+
+def run_execute_cadquery(code: str, output_path: str = DEFAULT_CADQUERY_OUTPUT_PATH, prompt: str | None = None) -> str:
+    try:
+        if not code or not code.strip():
+            return json_response({
+                "ok": False,
+                "stage": "input",
+                "error_type": "EmptyCode",
+                "error": "execute_cadquery requires non-empty CadQuery code.",
+                "traceback_tail": "",
+                "stdout": "",
+                "stderr": "",
+            })
+
+        run_dir, output, run_id = resolve_run_output(output_path)
+        output_root = run_dir.parent.parent
+    except Exception as exc:
+        return json_response({
+            "ok": False,
+            "stage": "input",
+            "error_type": type(exc).__name__,
+            "error": str(exc),
+            "traceback_tail": "",
+            "stdout": "",
+            "stderr": "",
+        })
+
+    request = {
+        "code": code,
+        "output_path": str(output),
+    }
+
+    try:
+        process = subprocess.run(
+            [sys.executable, "-c", CADQUERY_RUNNER],
+            input=json.dumps(request, ensure_ascii=False),
+            cwd=WORKDIR,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except subprocess.TimeoutExpired as exc:
+        return json_response({
+            "ok": False,
+            "stage": "execution",
+            "error_type": "TimeoutExpired",
+            "error": "CadQuery execution timed out after 120 seconds.",
+            "traceback_tail": "",
+            "stdout": exc.stdout[-4000:] if exc.stdout else "",
+            "stderr": exc.stderr[-4000:] if exc.stderr else "",
+        })
+    except Exception as exc:
+        return json_response({
+            "ok": False,
+            "stage": "subprocess",
+            "error_type": type(exc).__name__,
+            "error": str(exc),
+            "traceback_tail": "",
+            "stdout": "",
+            "stderr": "",
+        })
+
+    raw_output = process.stdout.strip()
+    if not raw_output:
+        return json_response({
+            "ok": False,
+            "stage": "subprocess",
+            "error_type": "NoRunnerOutput",
+            "error": "CadQuery runner returned no JSON output.",
+            "traceback_tail": "",
+            "stdout": "",
+            "stderr": process.stderr[-4000:],
+        })
+
+    try:
+        payload = json.loads(raw_output.splitlines()[-1])
+    except Exception as exc:
+        return json_response({
+            "ok": False,
+            "stage": "subprocess",
+            "error_type": type(exc).__name__,
+            "error": f"Failed to parse CadQuery runner output: {exc}",
+            "traceback_tail": "",
+            "stdout": raw_output[-4000:],
+            "stderr": process.stderr[-4000:],
+        })
+
+    if process.returncode != 0 and payload.get("ok") is not False:
+        payload = {
+            "ok": False,
+            "stage": "subprocess",
+            "error_type": "RunnerFailed",
+            "error": f"CadQuery runner exited with code {process.returncode}.",
+            "traceback_tail": "",
+            "stdout": raw_output[-4000:],
+            "stderr": process.stderr[-4000:],
+        }
+
+    if payload.get("ok") and payload.get("output_path"):
+        exported_path = Path(payload["output_path"])
+        manifest_path = write_manifest(
+            run_dir=run_dir,
+            run_id=run_id,
+            requested_output_path=output_path,
+            output_path=exported_path,
+            code=code,
+            prompt=prompt,
+            payload=payload,
+        )
+        latest_warning = update_latest_link(output_root, run_dir)
+
+        payload["run_id"] = run_id
+        payload["run_dir"] = workspace_relative(run_dir)
+        payload["output_path"] = workspace_relative(exported_path)
+        payload["manifest_path"] = workspace_relative(manifest_path)
+        payload["latest_path"] = workspace_relative(output_root / "latest")
+        if latest_warning:
+            payload["warning"] = latest_warning
+
+    return json_response(payload)
+
+
+TOOL_SCHEMA = {
+    "name": "execute_cadquery",
+    "description": textwrap.dedent("""
+        Execute CadQuery Python code and export the result as a STEP file.
+        The code must assign the final CadQuery model to a variable named result.
+        cadquery is pre-imported as cq.
+        output_path is optional. If it is a .step/.stp file path, the file name is used inside a unique run directory.
+        If it is a directory path, model.step is written inside a unique run directory under that root.
+    """).strip(),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "code": {
+                "type": "string",
+                "description": "CadQuery Python code. It must assign the final model to variable 'result'.",
+            },
+            "output_path": {
+                "type": "string",
+                "description": "Optional workspace-relative STEP file path or output directory. Defaults to outputs/model.step.",
+            },
+        },
+        "required": ["code"],
+    },
+}
+

agent_core/tools/lux3d_tool.py

@@ -0,0 +1,306 @@
+import base64
+import hashlib
+import json
+import mimetypes
+import os
+import textwrap
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from agent_core.config import (
+    DEFAULT_LUX3D_OUTPUT_PATH,
+    IMAGE_SUFFIXES,
+    LUX3D_API_KEY_ENV,
+    LUX3D_CREATE_URL,
+    LUX3D_GET_URL,
+    LUX3D_POLL_INTERVAL_SECONDS,
+    LUX3D_TIMEOUT_SECONDS,
+)
+from agent_core.outputs import (
+    resolve_lux3d_run,
+    safe_path,
+    update_latest_link,
+    workspace_relative,
+    write_lux3d_manifest,
+)
+from agent_core.utils import json_response, tail_text
+
+
+def validate_image_path(image_path: str) -> Path:
+    if not image_path or not image_path.strip():
+        raise ValueError("image_path is required for image-to-3D generation.")
+
+    path = safe_path(image_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Image file does not exist: {image_path}")
+    if not path.is_file():
+        raise ValueError(f"image_path must be a file: {image_path}")
+    if path.suffix.lower() not in IMAGE_SUFFIXES:
+        raise ValueError(f"Unsupported image format: {path.suffix}. Use one of: {', '.join(IMAGE_SUFFIXES)}")
+    return path
+
+
+def image_to_data_url(image_path: Path) -> str:
+    mime_type = mimetypes.guess_type(str(image_path))[0]
+    if not mime_type:
+        mime_type = "image/jpeg" if image_path.suffix.lower() in (".jpg", ".jpeg") else f"image/{image_path.suffix.lower().lstrip('.')}"
+    encoded = base64.b64encode(image_path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{encoded}"
+
+
+def parse_lux3d_api_key() -> dict:
+    api_key = os.getenv(LUX3D_API_KEY_ENV, "").strip()
+    if not api_key:
+        raise ValueError(f"Missing {LUX3D_API_KEY_ENV}. Set it in your environment or .env file.")
+
+    try:
+        decoded = base64.b64decode(api_key, validate=True).decode("utf-8")
+    except Exception as exc:
+        raise ValueError(f"Invalid {LUX3D_API_KEY_ENV}: expected a base64-encoded API key.") from exc
+
+    parts = decoded.split(":")
+    if len(parts) != 4 or not all(parts):
+        raise ValueError(f"Invalid {LUX3D_API_KEY_ENV}: expected decoded format version:appkey:appsecret:appuid.")
+
+    version, appkey, appsecret, appuid = parts
+    return {
+        "version": version,
+        "appkey": appkey,
+        "appsecret": appsecret,
+        "appuid": appuid,
+    }
+
+
+def lux3d_query(credentials: dict, extra: dict | None = None) -> str:
+    timestamp = str(int(time.time() * 1000))
+    sign = hashlib.md5(
+        (credentials["appsecret"] + credentials["appkey"] + credentials["appuid"] + timestamp).encode("utf-8")
+    ).hexdigest()
+    params = {
+        "appuid": credentials["appuid"],
+        "appkey": credentials["appkey"],
+        "timestamp": timestamp,
+        "sign": sign,
+    }
+    if extra:
+        params.update(extra)
+    return urllib.parse.urlencode(params)
+
+
+def lux3d_json_request(method: str, url: str, payload: dict | None = None, timeout: int = 30) -> dict:
+    data = None
+    headers = {}
+    if payload is not None:
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Lux3D API HTTP {exc.code}: {tail_text(body)}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Lux3D API request failed: {exc.reason}") from exc
+
+    try:
+        return json.loads(raw)
+    except Exception as exc:
+        raise RuntimeError(f"Lux3D API returned invalid JSON: {tail_text(raw)}") from exc
+
+
+def lux3d_create_task(credentials: dict, image_data_url: str) -> str | int:
+    query = lux3d_query(credentials)
+    payload = lux3d_json_request("POST", f"{LUX3D_CREATE_URL}?{query}", {"img": image_data_url})
+    busid = payload.get("d")
+    if not busid:
+        raise RuntimeError(f"Lux3D create task response did not include busid: {payload}")
+    return busid
+
+
+def lux3d_get_task(credentials: dict, busid: str | int) -> dict:
+    query = lux3d_query(credentials, {"busid": busid})
+    payload = lux3d_json_request("GET", f"{LUX3D_GET_URL}?{query}")
+    data = payload.get("d")
+    if not isinstance(data, dict):
+        raise RuntimeError(f"Lux3D get task response did not include task data: {payload}")
+    return data
+
+
+def infer_lux3d_output_name(result_url: str) -> str:
+    parsed = urllib.parse.urlparse(result_url)
+    name = Path(urllib.parse.unquote(parsed.path)).name
+    if name and "." in name:
+        return name
+    return "model.glb"
+
+
+def download_lux3d_result(result_url: str, output_path: Path) -> None:
+    request = urllib.request.Request(result_url, headers={"User-Agent": "aigc-3dcad/0.1"})
+    try:
+        with urllib.request.urlopen(request, timeout=120) as response:
+            data = response.read()
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Lux3D result download HTTP {exc.code}: {tail_text(body)}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Lux3D result download failed: {exc.reason}") from exc
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_bytes(data)
+
+
+def run_generate_3d_model(
+    image_path: str,
+    output_path: str | None = None,
+    prompt: str | None = None,
+    poll_interval_seconds: int = LUX3D_POLL_INTERVAL_SECONDS,
+    timeout_seconds: int = LUX3D_TIMEOUT_SECONDS,
+) -> str:
+    busid = None
+    status = None
+    result_url = None
+    output = None
+    poll_count = 0
+    run_dir = None
+    run_id = None
+    requested_output_path = output_path or DEFAULT_LUX3D_OUTPUT_PATH
+
+    try:
+        image = validate_image_path(image_path)
+        credentials = parse_lux3d_api_key()
+        output_root, run_dir, run_id, requested_output_name, requested_output_path = resolve_lux3d_run(output_path)
+        image_data_url = image_to_data_url(image)
+    except Exception as exc:
+        return json_response({
+            "ok": False,
+            "stage": "input",
+            "error_type": type(exc).__name__,
+            "error": str(exc),
+            "busid": busid,
+        })
+
+    try:
+        busid = lux3d_create_task(credentials, image_data_url)
+        deadline = time.time() + timeout_seconds
+
+        while True:
+            if time.time() >= deadline:
+                raise TimeoutError(f"Lux3D task timed out after {timeout_seconds} seconds.")
+
+            time.sleep(poll_interval_seconds)
+            poll_count += 1
+            task = lux3d_get_task(credentials, busid)
+            raw_status = task.get("status")
+            status = int(raw_status) if raw_status is not None else None
+
+            if status in (0, 1):
+                continue
+
+            if status == 3:
+                outputs = task.get("outputs") or []
+                result_url = next(
+                    (item.get("content") for item in outputs if isinstance(item, dict) and item.get("content")),
+                    None,
+                )
+                if not result_url:
+                    raise RuntimeError(f"Lux3D task succeeded but did not include a result URL: {task}")
+
+                output_name = requested_output_name or infer_lux3d_output_name(result_url)
+                output = run_dir / output_name
+                download_lux3d_result(result_url, output)
+                manifest_path = write_lux3d_manifest(
+                    run_dir=run_dir,
+                    run_id=run_id,
+                    prompt=prompt,
+                    image_path=image,
+                    requested_output_path=requested_output_path,
+                    output_path=output,
+                    busid=busid,
+                    status=status,
+                    result_url=result_url,
+                    poll_count=poll_count,
+                )
+                latest_warning = update_latest_link(output_root, run_dir)
+                payload = {
+                    "ok": True,
+                    "stage": "done",
+                    "run_id": run_id,
+                    "run_dir": workspace_relative(run_dir),
+                    "output_path": workspace_relative(output),
+                    "manifest_path": workspace_relative(manifest_path),
+                    "latest_path": workspace_relative(output_root / "latest"),
+                    "busid": busid,
+                    "status": status,
+                    "result_url": result_url,
+                    "poll_count": poll_count,
+                }
+                if latest_warning:
+                    payload["warning"] = latest_warning
+                return json_response(payload)
+
+            if status == 4:
+                raise RuntimeError(f"Lux3D task failed: {task}")
+
+            raise RuntimeError(f"Lux3D task returned unknown status {raw_status}: {task}")
+    except Exception as exc:
+        manifest_path = None
+        if run_dir and run_id:
+            manifest_path = write_lux3d_manifest(
+                run_dir=run_dir,
+                run_id=run_id,
+                prompt=prompt,
+                image_path=image,
+                requested_output_path=requested_output_path,
+                output_path=output,
+                busid=busid,
+                status=status,
+                result_url=result_url,
+                poll_count=poll_count,
+                error=str(exc),
+            )
+
+        payload = {
+            "ok": False,
+            "stage": "lux3d",
+            "error_type": type(exc).__name__,
+            "error": str(exc),
+            "busid": busid,
+            "status": status,
+            "result_url": result_url,
+            "poll_count": poll_count,
+        }
+        if manifest_path:
+            payload["run_id"] = run_id
+            payload["run_dir"] = workspace_relative(run_dir)
+            payload["manifest_path"] = workspace_relative(manifest_path)
+        return json_response(payload)
+
+
+TOOL_SCHEMA = {
+    "name": "generate_3d_model",
+    "description": textwrap.dedent("""
+        Generate a non-precise 3D model from a local image using the Lux3D image-to-3D API.
+        The input is a workspace-relative image path, not image bytes or base64 text.
+        The tool reads the image, creates a Lux3D task, polls for completion, downloads the result, and writes a manifest.
+    """).strip(),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "image_path": {
+                "type": "string",
+                "description": "Workspace-relative path to a source image file. Supported formats: .png, .jpg, .jpeg, .webp.",
+            },
+            "output_path": {
+                "type": "string",
+                "description": "Optional workspace-relative model file path or output directory. Defaults to outputs.",
+            },
+        },
+        "required": ["image_path"],
+    },
+}
+

agent_core/utils.py

@@ -0,0 +1,12 @@
+import json
+
+
+def json_response(payload: dict) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def tail_text(text: str, limit: int = 4000) -> str:
+    if not text:
+        return ""
+    return text[-limit:]
+

agent_loop.py

@@ -1,816 +1,52 @@
-import base64
-import hashlib
-import json
-import mimetypes
-import os
-import subprocess
-import sys
-import textwrap
-import time
-import urllib.error
-import urllib.parse
-import urllib.request
-from datetime import datetime
-from pathlib import Path
-from uuid import uuid4
+"""Backward-compatible entrypoint for the terminal agent.
 
-try:
-    from dotenv import load_dotenv
-except ImportError:
-    def load_dotenv(*args, **kwargs):
-        return False
-
-load_dotenv(override=True)
-
-if os.getenv("ANTHROPIC_BASE_URL"):
-    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
-
-WORKDIR = Path.cwd()
-DEFAULT_CADQUERY_OUTPUT_PATH = "outputs/model.step"
-DEFAULT_LUX3D_OUTPUT_PATH = "outputs"
-STEP_SUFFIXES = (".step", ".stp")
-IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp")
-LUX3D_API_KEY_ENV = "LUX3D_API_KEY"
-LUX3D_CREATE_URL = "https://api.luxreal.ai/global/lux3d/generate/task/create"
-LUX3D_GET_URL = "https://api.luxreal.ai/global/lux3d/generate/task/get"
-LUX3D_POLL_INTERVAL_SECONDS = 12
-LUX3D_TIMEOUT_SECONDS = 600
-
-SYSTEM = f"""
-You are a CAD and 3D model generation agent at {WORKDIR}.
-
-You have two tools:
-- execute_cadquery: use it for precise CAD, dimensioned parts, parametric geometry, engineering models, and STEP/CAD output.
-- generate_3d_model: use it when the user provides an image path and asks for a 3D model, mesh, GLB, OBJ, or other non-precise 3D asset.
-
-For CadQuery tasks:
-- Write CadQuery Python code.
-- The code must assign the final model to a variable named result.
-- You may use cadquery as cq; it is pre-imported by the tool.
-- Call execute_cadquery with the code and optional output_path.
-- Each successful tool call writes into a unique run directory to avoid overwriting previous models.
-- If execute_cadquery returns ok=false, inspect the structured error, fix the code, and call execute_cadquery again.
-
-For image-to-3D tasks:
-- The user must provide a workspace-relative image path.
-- If the user asks for image-to-3D generation but does not provide an image path, ask for the image path. Do not guess.
-- Call generate_3d_model with the image_path and optional output_path.
-- Do not ask the user to read files, convert images to base64, call APIs, or download results manually.
-
-When a tool returns ok=true, report output_path, run_dir, and manifest_path to the user.
-
-Do not ask the user to run commands or create files manually.
-""".strip()
-
-
-def get_client():
-    from anthropic import Anthropic
-
-    return Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
-
-
-def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
-        raise ValueError(f"Path escapes workspace: {p}")
-    return path
-
-
-def workspace_relative(path: Path) -> str:
-    return str(path.relative_to(WORKDIR))
-
-
-def new_run_id() -> str:
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    return f"{timestamp}_{uuid4().hex[:6]}"
-
-
-def tail_text(text: str, limit: int = 4000) -> str:
-    if not text:
-        return ""
-    return text[-limit:]
-
-
-def allocate_run_dir(output_root: Path) -> tuple[Path, str]:
-    for _ in range(20):
-        run_id = new_run_id()
-        run_dir = output_root / "runs" / run_id
-        if not run_dir.exists():
-            return run_dir, run_id
-
-    raise RuntimeError("Failed to allocate a unique output run directory.")
-
-
-def resolve_run_output(requested_output_path: str) -> tuple[Path, Path, str]:
-    requested_path = safe_path(requested_output_path)
-    suffix = requested_path.suffix.lower()
-
-    if suffix in STEP_SUFFIXES:
-        output_root = requested_path.parent
-        output_name = requested_path.name
-    elif suffix:
-        raise ValueError("Only STEP output is supported in this version. Use a .step/.stp file path or a directory path.")
-    else:
-        output_root = requested_path
-        output_name = "model.step"
-
-    run_dir, run_id = allocate_run_dir(output_root)
-    return run_dir, run_dir / output_name, run_id
-
-
-def resolve_lux3d_run(output_path: str | None) -> tuple[Path, Path, str, str | None, str]:
-    requested_output_path = output_path or DEFAULT_LUX3D_OUTPUT_PATH
-    requested_path = safe_path(requested_output_path)
-    if requested_path.suffix:
-        output_root = requested_path.parent
-        output_name = requested_path.name
-    else:
-        output_root = requested_path
-        output_name = None
-
-    run_dir, run_id = allocate_run_dir(output_root)
-    return output_root, run_dir, run_id, output_name, requested_output_path
-
-
-def update_latest_link(output_root: Path, run_dir: Path) -> str | None:
-    latest = output_root / "latest"
-    try:
-        if latest.is_symlink() or latest.is_file():
-            latest.unlink()
-        elif latest.exists():
-            return f"Skipped latest link because {workspace_relative(latest)} already exists and is not a symlink."
-
-        latest.symlink_to(Path("runs") / run_dir.name, target_is_directory=True)
-    except OSError as exc:
-        return f"Failed to update latest link: {exc}"
-
-    return None
-
-
-def write_manifest(
-    run_dir: Path,
-    run_id: str,
-    requested_output_path: str,
-    output_path: Path,
-    code: str,
-    prompt: str | None,
-    payload: dict,
-) -> Path:
-    manifest_path = run_dir / "manifest.json"
-    manifest_path.parent.mkdir(parents=True, exist_ok=True)
-    manifest = {
-        "run_id": run_id,
-        "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
-        "prompt": prompt,
-        "requested_output_path": requested_output_path,
-        "output_path": workspace_relative(output_path),
-        "format": output_path.suffix.lstrip(".").lower(),
-        "code": code,
-        "stdout": payload.get("stdout", ""),
-        "stderr": payload.get("stderr", ""),
-    }
-    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
-    return manifest_path
-
-
-def write_lux3d_manifest(
-    run_dir: Path,
-    run_id: str,
-    prompt: str | None,
-    image_path: Path,
-    requested_output_path: str,
-    output_path: Path | None,
-    busid: str | int | None,
-    status: int | None,
-    result_url: str | None,
-    poll_count: int,
-    error: str | None = None,
-) -> Path:
-    manifest_path = run_dir / "manifest.json"
-    manifest_path.parent.mkdir(parents=True, exist_ok=True)
-    manifest = {
-        "run_id": run_id,
-        "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
-        "generator": "lux3d",
-        "prompt": prompt,
-        "image_path": workspace_relative(image_path),
-        "requested_output_path": requested_output_path,
-        "output_path": workspace_relative(output_path) if output_path else None,
-        "busid": busid,
-        "status": status,
-        "result_url": result_url,
-        "poll_count": poll_count,
-        "error": error,
-    }
-    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
-    return manifest_path
-
-
-def validate_image_path(image_path: str) -> Path:
-    if not image_path or not image_path.strip():
-        raise ValueError("image_path is required for image-to-3D generation.")
-
-    path = safe_path(image_path)
-    if not path.exists():
-        raise FileNotFoundError(f"Image file does not exist: {image_path}")
-    if not path.is_file():
-        raise ValueError(f"image_path must be a file: {image_path}")
-    if path.suffix.lower() not in IMAGE_SUFFIXES:
-        raise ValueError(f"Unsupported image format: {path.suffix}. Use one of: {', '.join(IMAGE_SUFFIXES)}")
-    return path
-
-
-def image_to_data_url(image_path: Path) -> str:
-    mime_type = mimetypes.guess_type(str(image_path))[0]
-    if not mime_type:
-        mime_type = "image/jpeg" if image_path.suffix.lower() in (".jpg", ".jpeg") else f"image/{image_path.suffix.lower().lstrip('.')}"
-    encoded = base64.b64encode(image_path.read_bytes()).decode("ascii")
-    return f"data:{mime_type};base64,{encoded}"
-
-
-def parse_lux3d_api_key() -> dict:
-    api_key = os.getenv(LUX3D_API_KEY_ENV, "").strip()
-    if not api_key:
-        raise ValueError(f"Missing {LUX3D_API_KEY_ENV}. Set it in your environment or .env file.")
-
-    try:
-        decoded = base64.b64decode(api_key, validate=True).decode("utf-8")
-    except Exception as exc:
-        raise ValueError(f"Invalid {LUX3D_API_KEY_ENV}: expected a base64-encoded API key.") from exc
-
-    parts = decoded.split(":")
-    if len(parts) != 4 or not all(parts):
-        raise ValueError(f"Invalid {LUX3D_API_KEY_ENV}: expected decoded format version:appkey:appsecret:appuid.")
-
-    version, appkey, appsecret, appuid = parts
-    return {
-        "version": version,
-        "appkey": appkey,
-        "appsecret": appsecret,
-        "appuid": appuid,
-    }
-
-
-def lux3d_query(credentials: dict, extra: dict | None = None) -> str:
-    timestamp = str(int(time.time() * 1000))
-    sign = hashlib.md5(
-        (credentials["appsecret"] + credentials["appkey"] + credentials["appuid"] + timestamp).encode("utf-8")
-    ).hexdigest()
-    params = {
-        "appuid": credentials["appuid"],
-        "appkey": credentials["appkey"],
-        "timestamp": timestamp,
-        "sign": sign,
-    }
-    if extra:
-        params.update(extra)
-    return urllib.parse.urlencode(params)
-
-
-def lux3d_json_request(method: str, url: str, payload: dict | None = None, timeout: int = 30) -> dict:
-    data = None
-    headers = {}
-    if payload is not None:
-        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
-        headers["Content-Type"] = "application/json"
-
-    request = urllib.request.Request(url, data=data, headers=headers, method=method)
-    try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            raw = response.read().decode("utf-8")
-    except urllib.error.HTTPError as exc:
-        body = exc.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"Lux3D API HTTP {exc.code}: {tail_text(body)}") from exc
-    except urllib.error.URLError as exc:
-        raise RuntimeError(f"Lux3D API request failed: {exc.reason}") from exc
-
-    try:
-        return json.loads(raw)
-    except Exception as exc:
-        raise RuntimeError(f"Lux3D API returned invalid JSON: {tail_text(raw)}") from exc
-
-
-def lux3d_create_task(credentials: dict, image_data_url: str) -> str | int:
-    query = lux3d_query(credentials)
-    payload = lux3d_json_request("POST", f"{LUX3D_CREATE_URL}?{query}", {"img": image_data_url})
-    busid = payload.get("d")
-    if not busid:
-        raise RuntimeError(f"Lux3D create task response did not include busid: {payload}")
-    return busid
-
-
-def lux3d_get_task(credentials: dict, busid: str | int) -> dict:
-    query = lux3d_query(credentials, {"busid": busid})
-    payload = lux3d_json_request("GET", f"{LUX3D_GET_URL}?{query}")
-    data = payload.get("d")
-    if not isinstance(data, dict):
-        raise RuntimeError(f"Lux3D get task response did not include task data: {payload}")
-    return data
-
-
-def infer_lux3d_output_name(result_url: str) -> str:
-    parsed = urllib.parse.urlparse(result_url)
-    name = Path(urllib.parse.unquote(parsed.path)).name
-    if name and "." in name:
-        return name
-    return "model.glb"
-
-
-def download_lux3d_result(result_url: str, output_path: Path) -> None:
-    request = urllib.request.Request(result_url, headers={"User-Agent": "aigc-3dcad/0.1"})
-    try:
-        with urllib.request.urlopen(request, timeout=120) as response:
-            data = response.read()
-    except urllib.error.HTTPError as exc:
-        body = exc.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"Lux3D result download HTTP {exc.code}: {tail_text(body)}") from exc
-    except urllib.error.URLError as exc:
-        raise RuntimeError(f"Lux3D result download failed: {exc.reason}") from exc
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_bytes(data)
-
-
-CADQUERY_RUNNER = r"""
-import contextlib
-import io
-import json
-import sys
-import traceback
-from pathlib import Path
-
-stdout_buffer = io.StringIO()
-stderr_buffer = io.StringIO()
-
-
-def tail(text, limit=4000):
-    if not text:
-        return ""
-    return text[-limit:]
-
-
-def fail(stage, exc=None, error_type=None, error=None):
-    payload = {
-        "ok": False,
-        "stage": stage,
-        "error_type": error_type or (type(exc).__name__ if exc else "Error"),
-        "error": error or (str(exc) if exc else ""),
-        "traceback_tail": tail(traceback.format_exc() if exc else ""),
-        "stdout": tail(stdout_buffer.getvalue()),
-        "stderr": tail(stderr_buffer.getvalue()),
-    }
-    print(json.dumps(payload, ensure_ascii=False))
-
-
-try:
-    request = json.loads(sys.stdin.read())
-    code = request["code"]
-    output_path = Path(request["output_path"])
-except Exception as exc:
-    fail("input", exc)
-    sys.exit(0)
-
-try:
-    import cadquery as cq
-except Exception as exc:
-    fail("import", exc)
-    sys.exit(0)
-
-try:
-    compiled = compile(code, "<cadquery_code>", "exec")
-except Exception as exc:
-    fail("syntax", exc)
-    sys.exit(0)
-
-namespace = {
-    "__name__": "__cadquery_user_code__",
-    "cq": cq,
-}
-
-try:
-    with contextlib.redirect_stdout(stdout_buffer), contextlib.redirect_stderr(stderr_buffer):
-        exec(compiled, namespace)
-except Exception as exc:
-    fail("execution", exc)
-    sys.exit(0)
-
-if "result" not in namespace:
-    fail("result", error_type="MissingResult", error="CadQuery code must assign the final model to variable 'result'.")
-    sys.exit(0)
-
-result = namespace["result"]
-if result is None:
-    fail("result", error_type="InvalidResult", error="'result' is None.")
-    sys.exit(0)
-
-exportable_types = tuple(
-    value
-    for name in ("Workplane", "Shape", "Assembly", "Sketch")
-    for value in [getattr(cq, name, None)]
-    if isinstance(value, type)
-)
-
-is_exportable = isinstance(result, exportable_types)
-if isinstance(result, (list, tuple)) and result:
-    is_exportable = all(isinstance(item, exportable_types) for item in result)
-
-if not is_exportable:
-    fail(
-        "result",
-        error_type="InvalidResultType",
-        error=f"'result' must be a CadQuery object or a non-empty list/tuple of CadQuery objects, got {type(result).__name__}.",
-    )
-    sys.exit(0)
-
-try:
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    cq.exporters.export(result, str(output_path))
-except Exception as exc:
-    fail("export", exc)
-    sys.exit(0)
-
-payload = {
-    "ok": True,
-    "stage": "done",
-    "output_path": str(output_path),
-    "stdout": tail(stdout_buffer.getvalue()),
-    "stderr": tail(stderr_buffer.getvalue()),
-}
-print(json.dumps(payload, ensure_ascii=False))
+New code should import from agent_core.* modules directly. This file remains so
+existing commands like `python agent_loop.py` keep working.
 """
 
-
-def _json_response(payload: dict) -> str:
-    return json.dumps(payload, ensure_ascii=False, indent=2)
-
-
-def run_execute_cadquery(code: str, output_path: str = DEFAULT_CADQUERY_OUTPUT_PATH, prompt: str | None = None) -> str:
-    try:
-        if not code or not code.strip():
-            return _json_response({
-                "ok": False,
-                "stage": "input",
-                "error_type": "EmptyCode",
-                "error": "execute_cadquery requires non-empty CadQuery code.",
-                "traceback_tail": "",
-                "stdout": "",
-                "stderr": "",
-            })
-
-        run_dir, output, run_id = resolve_run_output(output_path)
-        output_root = run_dir.parent.parent
-    except Exception as exc:
-        return _json_response({
-            "ok": False,
-            "stage": "input",
-            "error_type": type(exc).__name__,
-            "error": str(exc),
-            "traceback_tail": "",
-            "stdout": "",
-            "stderr": "",
-        })
-
-    request = {
-        "code": code,
-        "output_path": str(output),
-    }
-
-    try:
-        process = subprocess.run(
-            [sys.executable, "-c", CADQUERY_RUNNER],
-            input=json.dumps(request, ensure_ascii=False),
-            cwd=WORKDIR,
-            capture_output=True,
-            text=True,
-            timeout=120,
-        )
-    except subprocess.TimeoutExpired as exc:
-        return _json_response({
-            "ok": False,
-            "stage": "execution",
-            "error_type": "TimeoutExpired",
-            "error": "CadQuery execution timed out after 120 seconds.",
-            "traceback_tail": "",
-            "stdout": exc.stdout[-4000:] if exc.stdout else "",
-            "stderr": exc.stderr[-4000:] if exc.stderr else "",
-        })
-    except Exception as exc:
-        return _json_response({
-            "ok": False,
-            "stage": "subprocess",
-            "error_type": type(exc).__name__,
-            "error": str(exc),
-            "traceback_tail": "",
-            "stdout": "",
-            "stderr": "",
-        })
-
-    raw_output = process.stdout.strip()
-    if not raw_output:
-        return _json_response({
-            "ok": False,
-            "stage": "subprocess",
-            "error_type": "NoRunnerOutput",
-            "error": "CadQuery runner returned no JSON output.",
-            "traceback_tail": "",
-            "stdout": "",
-            "stderr": process.stderr[-4000:],
-        })
-
-    try:
-        payload = json.loads(raw_output.splitlines()[-1])
-    except Exception as exc:
-        return _json_response({
-            "ok": False,
-            "stage": "subprocess",
-            "error_type": type(exc).__name__,
-            "error": f"Failed to parse CadQuery runner output: {exc}",
-            "traceback_tail": "",
-            "stdout": raw_output[-4000:],
-            "stderr": process.stderr[-4000:],
-        })
-
-    if process.returncode != 0 and payload.get("ok") is not False:
-        payload = {
-            "ok": False,
-            "stage": "subprocess",
-            "error_type": "RunnerFailed",
-            "error": f"CadQuery runner exited with code {process.returncode}.",
-            "traceback_tail": "",
-            "stdout": raw_output[-4000:],
-            "stderr": process.stderr[-4000:],
-        }
-
-    if payload.get("ok") and payload.get("output_path"):
-        exported_path = Path(payload["output_path"])
-        manifest_path = write_manifest(
-            run_dir=run_dir,
-            run_id=run_id,
-            requested_output_path=output_path,
-            output_path=exported_path,
-            code=code,
-            prompt=prompt,
-            payload=payload,
-        )
-        latest_warning = update_latest_link(output_root, run_dir)
-
-        payload["run_id"] = run_id
-        payload["run_dir"] = workspace_relative(run_dir)
-        payload["output_path"] = workspace_relative(exported_path)
-        payload["manifest_path"] = workspace_relative(manifest_path)
-        payload["latest_path"] = workspace_relative(output_root / "latest")
-        if latest_warning:
-            payload["warning"] = latest_warning
-
-    return _json_response(payload)
-
-
-def run_generate_3d_model(
-    image_path: str,
-    output_path: str | None = None,
-    prompt: str | None = None,
-    poll_interval_seconds: int = LUX3D_POLL_INTERVAL_SECONDS,
-    timeout_seconds: int = LUX3D_TIMEOUT_SECONDS,
-) -> str:
-    busid = None
-    status = None
-    result_url = None
-    output = None
-    poll_count = 0
-    run_dir = None
-    run_id = None
-    requested_output_path = output_path or DEFAULT_LUX3D_OUTPUT_PATH
-
-    try:
-        image = validate_image_path(image_path)
-        credentials = parse_lux3d_api_key()
-        output_root, run_dir, run_id, requested_output_name, requested_output_path = resolve_lux3d_run(output_path)
-        image_data_url = image_to_data_url(image)
-    except Exception as exc:
-        return _json_response({
-            "ok": False,
-            "stage": "input",
-            "error_type": type(exc).__name__,
-            "error": str(exc),
-            "busid": busid,
-        })
-
-    try:
-        busid = lux3d_create_task(credentials, image_data_url)
-        deadline = time.time() + timeout_seconds
-
-        while True:
-            if time.time() >= deadline:
-                raise TimeoutError(f"Lux3D task timed out after {timeout_seconds} seconds.")
-
-            time.sleep(poll_interval_seconds)
-            poll_count += 1
-            task = lux3d_get_task(credentials, busid)
-            raw_status = task.get("status")
-            status = int(raw_status) if raw_status is not None else None
-
-            if status in (0, 1):
-                continue
-
-            if status == 3:
-                outputs = task.get("outputs") or []
-                result_url = next(
-                    (item.get("content") for item in outputs if isinstance(item, dict) and item.get("content")),
-                    None,
-                )
-                if not result_url:
-                    raise RuntimeError(f"Lux3D task succeeded but did not include a result URL: {task}")
-
-                output_name = requested_output_name or infer_lux3d_output_name(result_url)
-                output = run_dir / output_name
-                download_lux3d_result(result_url, output)
-                manifest_path = write_lux3d_manifest(
-                    run_dir=run_dir,
-                    run_id=run_id,
-                    prompt=prompt,
-                    image_path=image,
-                    requested_output_path=requested_output_path,
-                    output_path=output,
-                    busid=busid,
-                    status=status,
-                    result_url=result_url,
-                    poll_count=poll_count,
-                )
-                latest_warning = update_latest_link(output_root, run_dir)
-                payload = {
-                    "ok": True,
-                    "stage": "done",
-                    "run_id": run_id,
-                    "run_dir": workspace_relative(run_dir),
-                    "output_path": workspace_relative(output),
-                    "manifest_path": workspace_relative(manifest_path),
-                    "latest_path": workspace_relative(output_root / "latest"),
-                    "busid": busid,
-                    "status": status,
-                    "result_url": result_url,
-                    "poll_count": poll_count,
-                }
-                if latest_warning:
-                    payload["warning"] = latest_warning
-                return _json_response(payload)
-
-            if status == 4:
-                raise RuntimeError(f"Lux3D task failed: {task}")
-
-            raise RuntimeError(f"Lux3D task returned unknown status {raw_status}: {task}")
-    except Exception as exc:
-        manifest_path = None
-        if run_dir and run_id:
-            manifest_path = write_lux3d_manifest(
-                run_dir=run_dir,
-                run_id=run_id,
-                prompt=prompt,
-                image_path=image,
-                requested_output_path=requested_output_path,
-                output_path=output,
-                busid=busid,
-                status=status,
-                result_url=result_url,
-                poll_count=poll_count,
-                error=str(exc),
-            )
-
-        payload = {
-            "ok": False,
-            "stage": "lux3d",
-            "error_type": type(exc).__name__,
-            "error": str(exc),
-            "busid": busid,
-            "status": status,
-            "result_url": result_url,
-            "poll_count": poll_count,
-        }
-        if manifest_path:
-            payload["run_id"] = run_id
-            payload["run_dir"] = workspace_relative(run_dir)
-            payload["manifest_path"] = workspace_relative(manifest_path)
-        return _json_response(payload)
-
-
-# -- The dispatch map: {tool_name: handler} --
-TOOL_HANDLERS = {
-    "execute_cadquery": lambda **kw: run_execute_cadquery(
-        kw["code"],
-        kw.get("output_path", DEFAULT_CADQUERY_OUTPUT_PATH),
-    ),
-    "generate_3d_model": lambda **kw: run_generate_3d_model(
-        kw["image_path"],
-        kw.get("output_path"),
-    ),
-}
-
-TOOLS = [
-    {
-        "name": "execute_cadquery",
-        "description": textwrap.dedent("""
-            Execute CadQuery Python code and export the result as a STEP file.
-            The code must assign the final CadQuery model to a variable named result.
-            cadquery is pre-imported as cq.
-            output_path is optional. If it is a .step/.stp file path, the file name is used inside a unique run directory.
-            If it is a directory path, model.step is written inside a unique run directory under that root.
-        """).strip(),
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "code": {
-                    "type": "string",
-                    "description": "CadQuery Python code. It must assign the final model to variable 'result'.",
-                },
-                "output_path": {
-                    "type": "string",
-                    "description": "Optional workspace-relative STEP file path or output directory. Defaults to outputs/model.step.",
-                },
-            },
-            "required": ["code"],
-        },
-    },
-    {
-        "name": "generate_3d_model",
-        "description": textwrap.dedent("""
-            Generate a non-precise 3D model from a local image using the Lux3D image-to-3D API.
-            The input is a workspace-relative image path, not image bytes or base64 text.
-            The tool reads the image, creates a Lux3D task, polls for completion, downloads the result, and writes a manifest.
-        """).strip(),
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "image_path": {
-                    "type": "string",
-                    "description": "Workspace-relative path to a source image file. Supported formats: .png, .jpg, .jpeg, .webp.",
-                },
-                "output_path": {
-                    "type": "string",
-                    "description": "Optional workspace-relative model file path or output directory. Defaults to outputs.",
-                },
-            },
-            "required": ["image_path"],
-        },
-    },
-]
-
-
-def latest_user_prompt(messages: list) -> str | None:
-    for message in reversed(messages):
-        if message.get("role") == "user" and isinstance(message.get("content"), str):
-            return message["content"]
-    return None
-
-
-def agent_loop(messages: list):
-    client = get_client()
-    model = os.environ["MODEL_ID"]
-
-    while True:
-        response = client.messages.create(
-            model=model, system=SYSTEM, messages=messages,
-            tools=TOOLS, max_tokens=8000,
-        )
-        messages.append({"role": "assistant", "content": response.content})
-        if response.stop_reason != "tool_use":
-            return
-        results = []
-        prompt = latest_user_prompt(messages)
-        for block in response.content:
-            if block.type == "tool_use":
-                if block.name == "execute_cadquery":
-                    output = run_execute_cadquery(
-                        code=block.input["code"],
-                        output_path=block.input.get("output_path", DEFAULT_CADQUERY_OUTPUT_PATH),
-                        prompt=prompt,
-                    )
-                elif block.name == "generate_3d_model":
-                    output = run_generate_3d_model(
-                        image_path=block.input["image_path"],
-                        output_path=block.input.get("output_path"),
-                        prompt=prompt,
-                    )
-                else:
-                    handler = TOOL_HANDLERS.get(block.name)
-                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
-                print(f"> {block.name}: {output[:200]}")
-                results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
-        messages.append({"role": "user", "content": results})
+from agent_core.agent import TOOL_HANDLERS, TOOLS, agent_loop, latest_user_prompt
+from agent_core.config import (
+    DEFAULT_CADQUERY_OUTPUT_PATH,
+    DEFAULT_LUX3D_OUTPUT_PATH,
+    IMAGE_SUFFIXES,
+    LUX3D_API_KEY_ENV,
+    LUX3D_CREATE_URL,
+    LUX3D_GET_URL,
+    LUX3D_POLL_INTERVAL_SECONDS,
+    LUX3D_TIMEOUT_SECONDS,
+    STEP_SUFFIXES,
+    WORKDIR,
+    get_client,
+)
+from agent_core.outputs import (
+    allocate_run_dir,
+    new_run_id,
+    resolve_lux3d_run,
+    resolve_run_output,
+    safe_path,
+    update_latest_link,
+    workspace_relative,
+    write_lux3d_manifest,
+    write_manifest,
+)
+from agent_core.prompts import SYSTEM
+from agent_core.tools.cadquery_tool import CADQUERY_RUNNER, run_execute_cadquery
+from agent_core.tools.lux3d_tool import (
+    download_lux3d_result,
+    image_to_data_url,
+    infer_lux3d_output_name,
+    lux3d_create_task,
+    lux3d_get_task,
+    lux3d_json_request,
+    lux3d_query,
+    parse_lux3d_api_key,
+    run_generate_3d_model,
+    validate_image_path,
+)
+from agent_core.utils import json_response as _json_response
+from agent_core.utils import tail_text
+from cli import main
 
 
 if __name__ == "__main__":
-    history = []
-    while True:
-        try:
-            query = input("\033[36mcad agent >> \033[0m")
-        except (EOFError, KeyboardInterrupt):
-            break
-        if query.strip().lower() in ("q", "exit", ""):
-            break
-        history.append({"role": "user", "content": query})
-        agent_loop(history)
-        response_content = history[-1]["content"]
-        if isinstance(response_content, list):
-            for block in response_content:
-                if hasattr(block, "text"):
-                    print(block.text)
-        print()
+    main()

cli.py

@@ -0,0 +1,26 @@
+from agent_core.agent import agent_loop
+
+
+def main():
+    history = []
+    while True:
+        try:
+            query = input("\033[36mcad agent >> \033[0m")
+        except (EOFError, KeyboardInterrupt):
+            break
+        if query.strip().lower() in ("q", "exit", ""):
+            break
+
+        history.append({"role": "user", "content": query})
+        agent_loop(history)
+        response_content = history[-1]["content"]
+        if isinstance(response_content, list):
+            for block in response_content:
+                if hasattr(block, "text"):
+                    print(block.text)
+        print()
+
+
+if __name__ == "__main__":
+    main()
+