pal-code 0.1.0__py3-none-any.whl

pal/studio/planner.py

@@ -0,0 +1,205 @@
+"""The builder bot: it reads what the person wants and proposes a plan: which agents, which tools, what may be accessed, which model.
+
+The bot is a LOCAL model (the strongest one Ollama has). It is asked for one JSON object; the answer is untrusted, so it goes through the plan
+normaliser, which enforces every safety rule. If the model's answer cannot be read after one retry, simple keyword rules make the plan instead, and the
+plan says so. The bot only ever proposes: it cannot switch on a risky permission (see plan.py).
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+from pal.llm_wrapper.components.base import LLMSyscall
+from pal.llm_wrapper.modes import PROVIDER_KEYS
+from pal.studio import plan as planlib
+from pal.studio.catalog import OFFERED_TOOLS, PERMISSIONS, ROLES
+
+EXAMPLE = {
+    "product": {"name": "Meeting notes to action items", "summary": "A page where I paste meeting notes and get a list of action items.", "kind": "web_app"},
+    "roles": ["designer", "coder", "docs", "reviewer"],
+    "tools": [],
+    "permissions": {"write_project": True, "modify_own_files": True, "read_references": True, "network_access": False},
+    "model": {"mode": "local", "model": "<one of the installed models>"},
+    "steps": [{"role": "designer", "task": "Design the page layout and styles."}, {"role": "coder", "task": "Write the logic that finds action items."},
+              {"role": "docs", "task": "Write the README."}, {"role": "reviewer", "task": "Review all files and fix mistakes."}],
+    "reasons": {"role:designer": "the product has a user interface", "role:reviewer": "a second look catches mistakes small models make", "model": "the strongest local model"},
+    "metrics": False,
+}
+
+
+def system_prompt(info: dict) -> str:
+    tools = [t for t in OFFERED_TOOLS if t in info.get("ready_tools", OFFERED_TOOLS)]
+    from pal import tool_catalog
+    return "\n".join([
+        "You are the planner of Pal Studio. A person tells you what they want built; you choose HOW it will be built.",
+        "Reply with ONE JSON object and nothing else: no prose, no code fences.",
+        "",
+        "Agents you may choose (ids): " + "; ".join(f"{r.id} = {r.description}" for r in ROLES.values()),
+        "Tools you may choose (names; most builds need none): " + "; ".join(f"{t} = {tool_catalog.BY_NAME[t].summary}" for t in tools),
+        "Permissions (true/false): " + "; ".join(f"{p.id} = {p.description}" + (" YOU MAY ONLY SUGGEST THIS; the person switches it on" if p.risky else "") + (" (locked off)" if p.locked else "") for p in PERMISSIONS),
+        "Models: local (Ollama), installed: " + (", ".join(info.get("installed", [])) or "none") + ". Use mode \"local\" unless the product clearly needs a stronger model, "
+        "then use mode \"api\" with a provider (" + ", ".join(PROVIDER_KEYS) + ") and a model name.",
+        "Only choose what the product needs: a small page needs designer, coder and reviewer; a script may need only coder and tester. Always include coder.",
+        "Each step is {\"role\", \"task\"} in build order, at most 8, ending with the reviewer when there is one. kind is one of: " + ", ".join(planlib.KINDS) + ".",
+        "Give a short reason (under 20 words) for each role, tool and the model, under \"reasons\", keyed like role:coder, tool:calculator, model.",
+        "",
+        "Example of the shape:", json.dumps(EXAMPLE),
+    ])
+
+
+def extract_json(text: str) -> dict:
+    """The first complete JSON object in a model's reply (fences, prose before or after, and trailing commas are tolerated)."""
+    text = text.strip()
+    start = text.find("{")
+    while start >= 0:
+        depth, in_str, esc = 0, False, False
+        for i in range(start, len(text)):
+            c = text[i]
+            if in_str:
+                esc = (c == "\\" and not esc)
+                if c == '"' and not esc:
+                    in_str = False
+                continue
+            if c == '"':
+                in_str = True
+            elif c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+                if depth == 0:
+                    blob = re.sub(r",(\s*[}\]])", r"\1", text[start:i + 1])
+                    try:
+                        obj = json.loads(blob)
+                        if isinstance(obj, dict):
+                            return obj
+                    except ValueError:
+                        pass
+                    break
+        start = text.find("{", start + 1)
+    raise ValueError("no JSON object in the reply")
+
+
+# -- the fallback: simple keyword rules ------------------------------------------------------------------------------------------------------------
+_WEB = re.compile(r"\b(web ?site|web ?page|landing|page|web app|webapp|html|browser|dashboard|ui|interface|portfolio|calculator app|game)\b", re.I)
+_CLI = re.compile(r"\b(cli|command[- ]line|script|automation|scraper|converter|parser|csv|tool|bot)\b", re.I)
+_TEST = re.compile(r"\btests?\b|unit test|pytest", re.I)
+
+
+def heuristic_plan(command: str, info: dict) -> dict:
+    web, cli = bool(_WEB.search(command)), bool(_CLI.search(command))
+    kind = "web_app" if web or not cli else "cli_tool"
+    roles = ["designer", "coder", "docs", "reviewer"] if kind == "web_app" else ["coder", "tester", "docs", "reviewer"]
+    if _TEST.search(command) and "tester" not in roles:
+        roles.insert(-2, "tester")
+    name = " ".join(command.split()[:6]).strip(" .,:;") or "My project"
+    return {"product": {"name": name[:60], "summary": " ".join(command.split())[:400], "kind": kind}, "roles": roles, "tools": [],
+            "model": {"mode": "local", "model": info.get("recommended") or ""},
+            "reasons": {"role:coder": "every build needs code written", "model": "the strongest local model that is installed"}}
+
+
+_ROLE_WORDS = {"designer": ("designer", "design", "styling", "layout"), "coder": ("coder", "code", "developer"), "tester": ("tester", "tests", "testing", "test"),
+               "docs": ("docs", "documentation", "readme", "docs writer"), "reviewer": ("reviewer", "review")}
+
+
+def heuristic_revise(plan: dict, instruction: str, info: dict) -> dict:
+    """A few plain edits when the model's answer cannot be read: add or remove an agent or a tool, switch the comparison on or off."""
+    text = instruction.lower()
+    new = json.loads(json.dumps(plan))
+    adding = bool(re.search(r"\b(add|include|also|with|use|need)\b", text))
+    removing = bool(re.search(r"\b(remove|drop|without|no|skip|don't|do not|exclude)\b", text))
+    for role, words in _ROLE_WORDS.items():
+        if any(re.search(rf"\b{re.escape(w)}\b", text) for w in words):
+            if removing and not adding and role in new["roles"]:
+                new["roles"].remove(role)
+            elif adding and role not in new["roles"]:
+                new["roles"].append(role)
+    from pal import tool_catalog
+    for t in OFFERED_TOOLS:
+        names = {t, t.replace("_", " "), tool_catalog.BY_NAME[t].title.lower()}
+        if any(n in text for n in names):
+            if removing and not adding and t in new["tools"]:
+                new["tools"].remove(t)
+            elif t not in new["tools"] and not removing:
+                new["tools"].append(t)
+    if re.search(r"\b(compare|comparison|twice|metrics?|with and without)\b", text):
+        new["metrics"] = not removing
+    new["steps"] = []                 # the steps follow the agents
+    return new
+
+
+@dataclass
+class PlanResult:
+    plan: dict
+    notes: list[str] = field(default_factory=list)
+    source: str = "model"                  # "model" | "fallback"
+    changes: list[str] = field(default_factory=list)
+    message: str = ""
+
+
+def describe(plan: dict, source: str, notes: list[str], model_note: str = "") -> str:
+    names = [ROLES[r].name for r in plan["roles"]]
+    pm = plan["model"]
+    parts = [f"Here is my plan for **{plan['product']['name']}**.",
+             f"Agents: {', '.join(names)}." + (f" Tools: {', '.join(plan['tools'])}." if plan["tools"] else " No extra tools."),
+             "It saves files only inside its own project folder, does not run the code it writes, and " + ("may go online." if plan["permissions"].get("network_access") else "does not go online.")]
+    parts.append(f"Model: {pm['model'] or 'none chosen'} ({'API, ' + pm['provider'] if pm['mode'] == 'api' else 'local, on this machine'})." + (f" {model_note}" if model_note else ""))
+    if source == "fallback":
+        parts.append("I could not read a plan from the model, so I used simple rules. Please check it.")
+    parts += notes[:4]
+    parts.append("Change anything on the right, or tell me what to change, then press Build.")
+    return " ".join(parts)
+
+
+class Planner:
+    def __init__(self, core, info: dict):
+        """`core` is a wrapper to chat with; `info` has installed (model names), recommended, ready_tools."""
+        self.core, self.info = core, info
+
+    def _ask(self, system: str, user: str, history: list[dict] | None = None) -> str:
+        msgs = [{"role": "system", "content": system}, *(history or []), {"role": "user", "content": user}]
+        return self.core.chat(LLMSyscall(messages=msgs, temperature=0.0, max_tokens=1800)).text
+
+    def _normalize(self, raw: dict, user_set) -> tuple[dict, list[str]]:
+        return planlib.normalize(raw, installed=self.info.get("installed", []), recommended=self.info.get("recommended"), user_set=user_set,
+                                 ready_tools=self.info.get("ready_tools"))
+
+    def _from_model(self, user: str, user_set) -> tuple[dict, list[str]] | None:
+        system, history = system_prompt(self.info), []  # type: (str, list[dict])
+        for attempt in range(2):
+            try:
+                reply = self._ask(system, user, history)
+                raw = extract_json(reply)
+                if not raw.get("roles") and not raw.get("product"):
+                    raise ValueError("that JSON has no product or roles")
+                return self._normalize(raw, user_set)
+            except Exception as e:  # noqa: BLE001  (the model is down, or its answer cannot be read)
+                if attempt == 0 and isinstance(e, ValueError):
+                    history = [{"role": "user", "content": user}, {"role": "assistant", "content": "(not valid)"}]
+                    user = f"Your last reply could not be read ({e}). Reply with ONE JSON object only, in the shape of the example."
+                    continue
+                return None
+        return None
+
+    def plan(self, command: str, user_set=()) -> PlanResult:
+        got = self._from_model(f"The person wants: {command}", user_set)
+        source = "model"
+        if got is None:
+            got, source = self._normalize(heuristic_plan(command, self.info), user_set), "fallback"
+        plan, notes = got
+        return PlanResult(plan, notes, source, [], describe(plan, source, notes))
+
+    def revise(self, plan: dict, instruction: str, user_set=()) -> PlanResult:
+        user = ("Here is the current plan as JSON:\n" + json.dumps(plan) + f"\n\nThe person says: {instruction}\n"
+                "Reply with the full updated plan as ONE JSON object. Change only what they asked for.")
+        got, source = self._from_model(user, user_set), "model"
+        if got is None:
+            got, source = self._normalize(heuristic_revise(plan, instruction, self.info), user_set), "fallback"
+        new, notes = got
+        changes = planlib.diff(plan, new)
+        msg = ("Done: " + "; ".join(changes) + "." if changes else "I made no change to the plan.")
+        if source == "fallback":
+            msg += " (I could not read the model's answer, so I applied simple rules: check the plan.)"
+        if not changes and source == "fallback":
+            msg = "I did not understand that. Try the controls on the right, or say for example 'add the tester' or 'build twice to compare'."
+        return PlanResult(new, notes, source, changes, " ".join([msg, *notes[:4]]))

pal/studio/policy.py

@@ -0,0 +1,69 @@
+"""Access policy: what a build may write, and what it may use. Enforced in code, with every refusal explained.
+
+A model's reply is untrusted text. Before any file is written it goes through `Policy.check_write`: the path must stay inside the project folder
+(no `..`, absolute paths, drive letters, hidden files, reserved Windows names), the kind of file must be allowed (programs and scripts are not: you add
+those yourself), and size and count limits hold. Paths are compared without regard to case, because Windows and macOS treat `Index.html` and
+`index.html` as one file.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pal.studio.catalog import PERMISSION_BY_ID, tool_needs
+from pal.terminal.policy import (  # noqa: E402,F401  (one copy of the path rules)
+    ALLOWED_EXTENSIONS,
+    ALLOWED_NAMES,
+    MAX_FILE_BYTES,
+    MAX_FILES,
+    MAX_TOTAL_BYTES,
+    PolicyError,
+    safe_path,
+)
+
+
+@dataclass
+class Decision:
+    allowed: bool
+    reason: str = ""
+    path: str = ""          # the cleaned path, when there is one
+
+
+@dataclass
+class Policy:
+    permissions: dict
+    written: dict = field(default_factory=dict)        # lower-cased path -> bytes written
+    blocked: list = field(default_factory=list)        # (path, reason)
+
+    def _no(self, path: str, reason: str) -> Decision:
+        self.blocked.append((path, reason))
+        return Decision(False, reason, path)
+
+    def check_write(self, raw_path: str, content: str) -> Decision:
+        try:
+            path = safe_path(raw_path)
+        except PolicyError as e:
+            return self._no(str(raw_path)[:80], str(e))
+        if not self.permissions.get("write_project", False):
+            return Decision(False, "saving is switched off (dry run): the file is shown but not saved", path)
+        size = len(content.encode("utf-8"))
+        key = path.lower()
+        if size > MAX_FILE_BYTES:
+            return self._no(path, f"too big ({size // 1000} KB; the limit is {MAX_FILE_BYTES // 1000} KB)")
+        if key in self.written and not self.permissions.get("modify_own_files", False):
+            return self._no(path, "it was already written in this build, and changing it is switched off")
+        if key not in self.written and len(self.written) >= MAX_FILES:
+            return self._no(path, f"too many files (the limit is {MAX_FILES})")
+        total = sum(v for k, v in self.written.items() if k != key) + size
+        if total > MAX_TOTAL_BYTES:
+            return self._no(path, f"the project would be over {MAX_TOTAL_BYTES // 1_000_000} MB")
+        self.written[key] = size
+        return Decision(True, "", path)
+
+    def check_tool(self, name: str) -> Decision:
+        need = tool_needs(name)
+        if need and not self.permissions.get(need, False):
+            return Decision(False, f"{name} needs '{PERMISSION_BY_ID[need].title}', which is off")
+        return Decision(True)
+
+    def allowed_tools(self, names) -> frozenset:
+        return frozenset(n for n in names if self.check_tool(n).allowed)

pal/studio/routes.py

@@ -0,0 +1,254 @@
+"""The web side of the Studio: a page, and the endpoints it talks to. Thin: the work is in the other modules."""
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from flask import Response, jsonify, render_template, request
+
+from pal.errors import UserInputError
+from pal.llm_wrapper.components.base import WrapperConfig
+from pal.llm_wrapper.modes import PROVIDER_KEYS, default_mode, describe_modes, providers_with_keys
+from pal.paths import data_dir
+from pal.studio import plan as planlib
+from pal.studio.catalog import catalog
+from pal.studio.editor import MAX_INSTRUCTION, lookup, save_file
+from pal.studio.planner import Planner
+from pal.studio.policy import MAX_FILE_BYTES, MAX_FILES, PolicyError, safe_path
+from pal.studio.runs import RunStore
+from pal.terminal.models import discover
+
+MAX_REFERENCES, MAX_REFERENCE_BYTES, MAX_REFERENCES_TOTAL = 8, 150_000, 400_000
+
+
+class _NoModel:
+    """Stands in for the planner's model when none can be reached: every call fails, so the rules-based plan is used."""
+
+    def chat(self, syscall):
+        raise ConnectionError("no local model is available")
+
+
+def clean_references(raw) -> list[dict]:
+    if raw in (None, []):
+        return []
+    if not isinstance(raw, list) or len(raw) > MAX_REFERENCES:
+        raise UserInputError(f"attach at most {MAX_REFERENCES} reference files")
+    out, total = [], 0
+    for r in raw:
+        if not isinstance(r, dict) or not isinstance(r.get("text"), str) or not isinstance(r.get("name"), str):
+            raise UserInputError("a reference file must have a name and text")
+        name = re.sub(r"[^A-Za-z0-9_. \-]", "_", Path(r["name"].replace("\\", "/")).name)[:80] or "reference.txt"
+        size = len(r["text"].encode("utf-8"))
+        total += size
+        if size > MAX_REFERENCE_BYTES or total > MAX_REFERENCES_TOTAL:
+            raise UserInputError(f"reference files are too big (at most {MAX_REFERENCE_BYTES // 1000} KB each and {MAX_REFERENCES_TOTAL // 1000} KB together)")
+        out.append({"name": name, "text": r["text"]})
+    return out
+
+
+def register_studio(app, service, *, planner_core: Callable | None = None, core_factory: Callable | None = None, discover_fn: Callable | None = None,
+                    hot_turns: int | None = None) -> RunStore:
+    """Add the Studio page and endpoints to the app. The three callables are for tests: the planner's model, the builder's model, local-model discovery."""
+    cfg = service.settings
+    home = Path(cfg.storage_dir).expanduser() if cfg.storage_dir else data_dir()
+    host = lambda: (cfg.local_llm.get("host") or "http://localhost:11434")  # noqa: E731
+
+    def num_ctx() -> int:
+        return cfg.studio.num_ctx
+
+    def local_core(model: str, ctx: int):
+        from pal.llm_wrapper import build_wrapper
+        return build_wrapper(WrapperConfig(backend="ollama", model=model, host=host(), extra={"timeout": 900, "litellm_params": {"num_ctx": ctx, "keep_alive": "30m"}}))
+
+    def default_core_factory(plan: dict, api_key: str | None):
+        from pal.chat.providers import build_api_core
+        m = plan["model"]
+        if m["mode"] == "api":
+            return build_api_core(m["provider"], m["model"], api_key)
+        if not m["model"]:
+            raise UserInputError("no local model is chosen: start Ollama and pull a model, or switch to an API model")
+        return local_core(m["model"], num_ctx())
+
+    runs = RunStore(home / "studio", core_factory or default_core_factory, max_runs=cfg.studio.max_runs, hot_turns=hot_turns)
+    app.extensions["studio_runs"] = runs
+
+    def local() -> dict:
+        found = (discover_fn or discover)(host())
+        if discover_fn is not None or not found.get("ok"):
+            return found
+        return fit_to_hardware(found)
+
+    def fit_to_hardware(found: dict) -> dict:
+        """Mark each installed model with how it fits this computer's GPU, and recommend the best one that fits (not just the largest)."""
+        from pal.terminal.backend import hardware
+        from pal.terminal.local_models import FIT_LABEL, api_only, best_installed, installed_fit
+        hw = hardware()
+        if api_only(hw):
+            return {"ok": False, "url": found.get("url"), "models": [], "recommended": None, "hardware": hw.summary(),
+                    "error": "No GPU on this computer, so Pal uses API models only: choose an API model (and paste a key) in the plan's Model step."}
+        fits = {r["name"]: r["fit"] for r in installed_fit(found["models"], hw)}
+        models = [{**m, "fit": fits.get(m["name"], ""), "label": m["label"] + (f" | {FIT_LABEL[fits[m['name']]]}" if m["name"] in fits else "")} for m in found["models"]]
+        best = best_installed(found["models"], hw) or found["recommended"]
+        return {**found, "models": models, "recommended": best, "hardware": hw.summary()}
+
+    def ready_tools() -> list[str]:
+        return [t["name"] for t in catalog(cfg.tools, os.environ)["tools"] if t["ready"]]
+
+    def info(model: str | None = None) -> tuple[dict, dict]:
+        loc = local()
+        installed = [m["name"] for m in loc["models"] if not m["embedding"]]
+        chosen = model if model in installed else loc["recommended"]
+        return {"installed": installed, "recommended": chosen, "ready_tools": ready_tools()}, loc
+
+    def planner_for(i: dict, loc: dict) -> Planner:
+        if not loc["ok"] or not i["recommended"]:
+            return Planner(_NoModel(), i)
+        if planner_core:
+            return Planner(planner_core(i["recommended"]), i)
+        return Planner(local_core(i["recommended"], cfg.studio.planner_num_ctx), i)
+
+    def body() -> dict:
+        data = request.get_json(silent=True)
+        if not isinstance(data, dict):
+            raise UserInputError("send a JSON object")
+        return data
+
+    def user_set(data: dict) -> list[str]:
+        v = data.get("user_set") or []
+        return [x for x in v if isinstance(x, str)] if isinstance(v, list) else []
+
+    def normalized(data: dict, i: dict) -> tuple[dict, list[str]]:
+        if not isinstance(data.get("plan"), dict):
+            raise UserInputError("send the plan")
+        return planlib.normalize(data["plan"], installed=i["installed"], recommended=i["recommended"], user_set=user_set(data), ready_tools=i["ready_tools"])
+
+    @app.get("/studio")
+    def studio_page():
+        resp = Response(render_template("studio.html"), mimetype="text/html")
+        # The page shows text a model wrote, so it may not run inline scripts or load anything from another site.
+        resp.headers["Content-Security-Policy"] = ("default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; "
+                                                   "base-uri 'none'; form-action 'none'; frame-ancestors 'none'")
+        return resp
+
+    @app.get("/api/studio/catalog")
+    def studio_catalog():
+        loc = local()
+        return jsonify({**catalog(cfg.tools, os.environ), "local": loc, "llm_modes": describe_modes(), "llm_mode": default_mode(), "providers": providers_with_keys(),
+                        "limits": {"num_ctx": num_ctx(), "max_files": MAX_FILES, "max_file_kb": MAX_FILE_BYTES // 1000, "max_references": MAX_REFERENCES, "max_reference_kb": MAX_REFERENCE_BYTES // 1000}})
+
+    @app.post("/api/studio/plan")
+    def studio_plan():
+        data = body()
+        command = (data.get("command") or "").strip() if isinstance(data.get("command"), str) else ""
+        if not command:
+            raise UserInputError("tell me what you want built")
+        if len(command) > 4000:
+            raise UserInputError("that is too long: describe it in a few sentences (under 4000 characters)")
+        i, loc = info(data.get("model") if isinstance(data.get("model"), str) else None)
+        r = planner_for(i, loc).plan(command, user_set(data))
+        return jsonify({"plan": r.plan, "notes": r.notes, "source": r.source, "message": r.message, "planner_model": i["recommended"], "local": {"ok": loc["ok"], "error": loc["error"]}})
+
+    @app.post("/api/studio/revise")
+    def studio_revise():
+        data = body()
+        instruction = (data.get("instruction") or "").strip() if isinstance(data.get("instruction"), str) else ""
+        if not instruction or len(instruction) > 2000:
+            raise UserInputError("say what to change (under 2000 characters)")
+        i, loc = info(data.get("model") if isinstance(data.get("model"), str) else None)
+        current, _ = normalized(data, i)
+        r = planner_for(i, loc).revise(current, instruction, user_set(data))
+        return jsonify({"plan": r.plan, "notes": r.notes, "source": r.source, "message": r.message, "changes": r.changes})
+
+    @app.post("/api/studio/validate")
+    def studio_validate():
+        data = body()
+        i, _ = info()
+        plan, notes = normalized(data, i)
+        return jsonify({"plan": plan, "notes": notes})
+
+    @app.post("/api/studio/run")
+    def studio_run():
+        data = body()
+        i, _ = info()
+        plan, notes = normalized(data, i)
+        key = data.get("api_key") if isinstance(data.get("api_key"), str) else None
+        m = plan["model"]
+        if m["mode"] == "api" and not (key or os.environ.get(PROVIDER_KEYS[m["provider"]])):
+            raise UserInputError(f"no API key for {m['provider']}: paste one, or switch to the local model")
+        run = runs.start(plan, clean_references(data.get("references")) if plan["permissions"].get("read_references") else [], key)
+        return jsonify({"run_id": run.id, "notes": notes})
+
+    @app.get("/api/studio/run/<run_id>")
+    def studio_run_status(run_id):
+        run = runs.get(run_id)
+        try:
+            since = int(request.args.get("since", "0"))
+        except ValueError:
+            raise UserInputError("since must be a number") from None
+        return jsonify({**run.summary(), "events": run.events_since(since)})
+
+    @app.post("/api/studio/run/<run_id>/cancel")
+    def studio_cancel(run_id):
+        runs.get(run_id).cancel.set()
+        return jsonify({"ok": True})
+
+    @app.get("/api/studio/run/<run_id>/files")
+    def studio_files(run_id):
+        state = runs.get(run_id).arm(request.args.get("arm", ""))
+        files = state.build.files if state.build else {}
+        return jsonify({"files": [{"path": p, "bytes": len(c.encode("utf-8"))} for p, c in sorted(files.items())]})
+
+    @app.get("/api/studio/run/<run_id>/file")
+    def studio_file(run_id):
+        state = runs.get(run_id).arm(request.args.get("arm", ""))
+        try:
+            path = safe_path(request.args.get("path", ""))
+        except PolicyError as e:
+            raise UserInputError(str(e)) from None
+        files = {p.lower(): (p, c) for p, c in (state.build.files if state.build else {}).items()}
+        if path.lower() not in files:
+            raise UserInputError("no such file in this build")
+        name, content = files[path.lower()]
+        limit = MAX_FILE_BYTES if request.args.get("full") == "1" else 60_000       # the editor needs the whole file: saving a shortened one would lose the rest
+        return jsonify({"path": name, "content": content[:limit], "truncated": len(content) > limit})
+
+    @app.put("/api/studio/run/<run_id>/file")
+    def studio_save_file(run_id):
+        data = body()
+        arm, path, content = (str(data.get(k)) if isinstance(data.get(k), str) else "" for k in ("arm", "path", "content"))
+        state = runs.editable(runs.get(run_id), arm)
+        return jsonify(save_file(state, path, content))
+
+    @app.post("/api/studio/run/<run_id>/ask")
+    def studio_ask(run_id):
+        """Ask Pal to change the open file (or answer a question about the project). Proposes only: nothing is saved until the person accepts."""
+        data = body()
+        instruction = (data.get("instruction") or "").strip() if isinstance(data.get("instruction"), str) else ""
+        if not instruction or len(instruction) > MAX_INSTRUCTION:
+            raise UserInputError(f"say what to change (under {MAX_INSTRUCTION} characters)")
+        run = runs.get(run_id)
+        arm = str(data.get("arm")) if isinstance(data.get("arm"), str) else ""
+        state = runs.editable(run, arm)
+        path = str(data.get("path")) if isinstance(data.get("path"), str) else ""
+        build = state.build
+        assert build is not None                                    # editable() checked it  # noqa: S101
+        if path and lookup(build.files, path) is None:
+            raise UserInputError("that file is not in this build")
+        key = data.get("api_key") if isinstance(data.get("api_key"), str) else None
+        m = run.plan["model"]
+        if m["mode"] == "api" and not (key or os.environ.get(PROVIDER_KEYS[m["provider"]])):
+            raise UserInputError(f"no API key for {m['provider']}: paste one, or switch to the local model")
+        return jsonify(runs.editor(run, arm, key).ask(build.files, path, instruction))
+
+    @app.get("/api/studio/run/<run_id>/download")
+    def studio_download(run_id):
+        run = runs.get(run_id)
+        arm = request.args.get("arm", "")
+        data = runs.zip_bytes(run, arm)
+        workspace = run.arm(arm).workspace
+        folder = workspace.name if workspace else "project"
+        return Response(data, mimetype="application/zip", headers={"Content-Disposition": f'attachment; filename="{folder}-{arm}.zip"'})
+
+    return runs