langstage-codraft 0.1.0__py3-none-any.whl

langstage_codraft/__init__.py

@@ -0,0 +1,42 @@
+"""langstage-codraft: the document stage for your LangGraph agent.
+
+Bring your own agent::
+
+    from langchain.agents import create_agent
+    from langstage_codraft import CodraftMiddleware
+
+    graph = create_agent("openai:gpt-4.1-mini", middleware=[CodraftMiddleware()])
+
+or a factory Codraft calls with its tools and middleware::
+
+    def make(tools, middleware):
+        return create_agent(my_model, tools=[*tools, *my_tools], middleware=middleware)
+
+then ``langstage-codraft run --agent my_agent.py:graph`` (or ``:make``).
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("langstage-codraft")
+except PackageNotFoundError:  # pragma: no cover - source checkout
+    __version__ = "0.0.0+local"
+
+
+def __getattr__(name: str):
+    # Lazy so `import langstage_codraft` (and the CLI's --version) stays fast.
+    if name == "CODRAFT_TOOLS":
+        from .tools import CODRAFT_TOOLS
+
+        return CODRAFT_TOOLS
+    if name == "CodraftMiddleware":
+        from .middleware import CodraftMiddleware
+
+        return CodraftMiddleware
+    if name == "CODRAFT_PROMPT":
+        from .middleware import CODRAFT_PROMPT
+
+        return CODRAFT_PROMPT
+    raise AttributeError(name)
+
+
+__all__ = ["CODRAFT_PROMPT", "CODRAFT_TOOLS", "CodraftMiddleware", "__version__"]

langstage_codraft/agent.py

@@ -0,0 +1,301 @@
+"""Resolve which agent a Codraft server runs.
+
+Three ways to bring an agent (``--agent path.py:obj``):
+
+* **a compiled graph** that already carries the tools, e.g.
+  ``create_agent(model, middleware=[CodraftMiddleware()])``. It is used as-is.
+* **a factory** ``def make(tools, middleware): ...``. Codraft calls it with
+  ``CODRAFT_TOOLS`` and ``[CodraftMiddleware()]``: the deployer builds the graph and
+  Codraft adds what this app needs (notes p.4).
+* **a compiled graph without the tools.** It still chats, but it cannot touch the
+  document. ``langstage-codraft check`` reports this.
+
+Without ``--agent``, a default agent is built from ``--model`` or ``[codraft] model``
+(or the first API key found). ``--demo`` runs a keyless scripted co-author that
+exercises the whole suggestion flow.
+"""
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import re
+import uuid
+from typing import Any
+
+from .middleware import CodraftMiddleware
+from .tools import CODRAFT_TOOLS, TOOL_NAMES
+
+OPENROUTER_BASE = "https://openrouter.ai/api/v1"
+DEFAULT_OPENROUTER_MODEL = "anthropic/claude-haiku-5.5"
+DEFAULT_OPENAI_MODEL = "gpt-5-mini"
+
+
+# ------------------------------------------------------------------------- models
+def default_model_spec() -> str | None:
+    if os.environ.get("OPENROUTER_API_KEY"):
+        return f"openrouter:{DEFAULT_OPENROUTER_MODEL}"
+    if os.environ.get("OPENAI_API_KEY"):
+        return f"openai:{DEFAULT_OPENAI_MODEL}"
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return "anthropic:claude-haiku-5-5"
+    return None
+
+
+def make_model(spec: str) -> Any:
+    """``openrouter:<slug>`` or any ``init_chat_model`` spec (``openai:gpt-4.1``…)."""
+    if spec.startswith("openrouter:"):
+        from langchain_openai import ChatOpenAI
+
+        key = os.environ.get("OPENROUTER_API_KEY")
+        if not key:
+            raise RuntimeError("OPENROUTER_API_KEY is not set (needed for an openrouter: model)")
+        return ChatOpenAI(model=spec.split(":", 1)[1], base_url=OPENROUTER_BASE, api_key=key,
+                          temperature=0.3, default_headers={"X-Title": "langstage-codraft"})
+    from langchain.chat_models import init_chat_model
+
+    return init_chat_model(spec)
+
+
+def research_tools() -> list:
+    """Keyless research helpers for the default agent: fetch a URL, and web search
+    when the optional ``ddgs`` package (``[search]`` extra) is installed."""
+    from langchain_core.tools import tool
+
+    @tool
+    def fetch_url(url: str, max_chars: int = 6000) -> str:
+        """Fetch a web page and return its readable text (truncated)."""
+        import httpx
+
+        try:
+            r = httpx.get(url, timeout=20, follow_redirects=True,
+                          headers={"User-Agent": "Mozilla/5.0 (langstage-codraft)"})
+            r.raise_for_status()
+        except Exception as exc:  # noqa: BLE001
+            return f"ERROR fetching {url}: {exc}"
+        from .textutil import extract_text
+
+        text = extract_text("page.html", r.content) if "html" in r.headers.get("content-type", "") else r.text
+        return text[: max(500, min(max_chars, 20000))]
+
+    tools = [fetch_url]
+    try:
+        from ddgs import DDGS
+
+        @tool
+        def web_search(query: str, max_results: int = 5) -> str:
+            """Search the web. Returns titles, urls and snippets to cite as references."""
+
+            try:
+                hits = list(DDGS().text(query, max_results=max(1, min(max_results, 10))))
+            except Exception as exc:  # noqa: BLE001
+                return f"ERROR searching: {exc}"
+            return "\n".join(f"- {h.get('title')} — {h.get('href')}\n  {h.get('body')}" for h in hits) or "No results."
+
+        tools.append(web_search)
+    except ImportError:
+        pass
+    return tools
+
+
+def build_default_agent(model_spec: str, *, extra_tools: list | None = None) -> Any:
+    from langchain.agents import create_agent
+
+    return create_agent(
+        make_model(model_spec),
+        tools=research_tools() + list(extra_tools or []),
+        middleware=[CodraftMiddleware()],
+        name="codraft",
+    )
+
+
+# --------------------------------------------------------------------- inspection
+def graph_tool_names(graph: Any) -> set[str]:
+    """Best-effort: the tool names a compiled graph's tool nodes can call."""
+    names: set[str] = set()
+    for node in (getattr(graph, "nodes", None) or {}).values():
+        for obj in (node, getattr(node, "bound", None), getattr(node, "runnable", None)):
+            tbn = getattr(obj, "tools_by_name", None)
+            if isinstance(tbn, dict):
+                names |= set(tbn)
+    return names
+
+
+def is_graph(obj: Any) -> bool:
+    return hasattr(obj, "aget_state") and hasattr(obj, "nodes")
+
+
+def resolve_agent_object(obj: Any) -> tuple[Any, str]:
+    """Turn a loaded spec object into (graph, kind)."""
+    if is_graph(obj):
+        return obj, "graph"
+    if callable(obj):
+        params = inspect.signature(obj).parameters
+        kwargs: dict[str, Any] = {}
+        if "tools" in params:
+            kwargs["tools"] = list(CODRAFT_TOOLS)
+        if "middleware" in params:
+            kwargs["middleware"] = [CodraftMiddleware(tools=[])] if "tools" in params else [CodraftMiddleware()]
+        g = obj(**kwargs)
+        if not is_graph(g):
+            raise TypeError(f"agent factory returned {type(g).__name__}, not a compiled LangGraph graph")
+        return g, "factory"
+    raise TypeError(f"agent spec resolved to {type(obj).__name__}; expected a compiled graph or a factory")
+
+
+def missing_tools(graph: Any) -> list[str]:
+    have = graph_tool_names(graph)
+    return sorted(TOOL_NAMES - have)
+
+
+# --------------------------------------------------------------------- demo agent
+def _last_human_idx(messages: list) -> int:
+    for i in range(len(messages) - 1, -1, -1):
+        if getattr(messages[i], "type", "") == "human":
+            return i
+    return -1
+
+
+def _call(name: str, args: dict) -> dict:
+    return {"name": name, "args": args, "id": f"call_{uuid.uuid4().hex[:12]}", "type": "tool_call"}
+
+
+def _demo_revise(block_text: str, comment: str) -> str:
+    c = comment.lower()
+    text = block_text.strip()
+    if any(w in c for w in ("short", "concise", "tighten", "trim")):
+        sentences = re.split(r"(?<=[.!?])\s+", text)
+        return " ".join(sentences[: max(1, len(sentences) // 2)])
+    if any(w in c for w in ("expand", "more detail", "elaborate", "longer")):
+        return text + "\n\nThis point deserves more detail: it shapes the reader's next decision, so it is spelled out here."
+    if any(w in c for w in ("formal", "professional")):
+        return text.replace("can't", "cannot").replace("don't", "do not").replace("it's", "it is")
+    return text + f"\n\n*Revised to address: “{comment.strip()}”.*"
+
+
+def demo_turn(messages: list) -> dict:
+    """The scripted co-author: returns {"content": str, "tool_calls": [...]}.
+
+    Deterministic and keyless. It follows the same tool path a real model would, so
+    the demo exercises the suggestion/approval flow end to end."""
+    i = _last_human_idx(messages)
+    human = messages[i] if i >= 0 else None
+    text = human.content if human is not None and isinstance(human.content, str) else ""
+    low = text.lower()
+    tool_msgs = [m for m in messages[i + 1:] if getattr(m, "type", "") == "tool"]
+    done = {m.name for m in tool_msgs}
+    last = tool_msgs[-1] if tool_msgs else None
+
+    if last is None:
+        if "comment" in low:
+            return {"content": "Let me look at the open comments, top to bottom.",
+                    "tool_calls": [_call("list_comments", {})]}
+        if any(w in low for w in ("layout", "look at", "view", "pages")):
+            return {"content": "", "tool_calls": [_call("view_pages", {})]}
+        if "reference" in low or "sources" in low:
+            return {"content": "", "tool_calls": [_call("compile_references", {})]}
+        if any(low.startswith(w) for w in ("write", "draft", "add")):
+            topic = re.sub(r"^(write|draft|add)\b(.*?\b(about|on)\b)?\s*(a|an|the)?\s*", "", text,
+                           flags=re.IGNORECASE).strip().rstrip(".") or "this topic"
+            body = (f"{topic[:1].upper()}{topic[1:]} matters because it changes what the reader can do next. "
+                    "This draft states the claim, gives one piece of evidence, and closes with the implication.")
+            return {"content": "", "tool_calls": [_call("propose_insert", {
+                "block_type": "text", "content": body, "note": f"Draft paragraph: {topic[:60]}"})]}
+        return {"content": "", "tool_calls": [_call("get_document", {})]}
+
+    if last.name == "list_comments":
+        found = re.findall(r"\[(cmt_\w+)\] \(open\) block \[(blk_\w+)\].*? — \w+: (.*)", last.content)
+        if not found:
+            return {"content": "There are no open comments on blocks, so there is nothing to address.", "tool_calls": []}
+        return {"content": "", "tool_calls": [_call("read_blocks", {"block_ids": [b for _, b, _ in found]})]}
+
+    if last.name == "read_blocks" and "propose_edit" not in done:
+        lc = next((m for m in tool_msgs if m.name == "list_comments"), None)
+        found = re.findall(r"\[(cmt_\w+)\] \(open\) block \[(blk_\w+)\].*? — \w+: (.*)", lc.content if lc else "")
+        bodies: dict[str, str] = {}
+        for chunk in re.split(r"\n\n(?=\[blk_)", last.content):
+            m = re.match(r"\[(blk_\w+)\] (\w[\w-]*) [^\n]*\n(.*)", chunk, re.DOTALL)
+            if m:
+                bodies[m.group(1)] = (m.group(2), re.sub(r"\n  ref: .*", "", m.group(3)).strip())
+        calls = []
+        for cid, bid, body in found:
+            btype, current = bodies.get(bid, ("text", ""))
+            if btype not in ("text", "callout", "heading"):
+                calls.append(_call("reply_to_comment", {
+                    "comment_id": cid,
+                    "message": f"The demo agent can only revise text; this is a {btype} block, so there's no tool for it."}))
+                continue
+            new = current.lstrip("# ").title() if btype == "heading" else _demo_revise(current, body)
+            calls.append(_call("propose_edit", {"block_id": bid, "content": new, "comment_id": cid,
+                                                "note": f"Addresses: {body.strip()[:80]}"}))
+            calls.append(_call("reply_to_comment", {"comment_id": cid,
+                                                    "message": "Proposed a revision; accept or reject it on the block."}))
+        return {"content": "", "tool_calls": calls}
+
+    if last.name in ("propose_edit", "reply_to_comment"):
+        n = sum(1 for m in tool_msgs if m.name == "propose_edit")
+        return {"content": f"Done. I proposed {n} edit(s), handling the comments from top to bottom. "
+                           "Each one is waiting on its block for you to accept or reject.", "tool_calls": []}
+    if last.name == "propose_insert":
+        return {"content": "I drafted a paragraph as a suggestion at the end of the document. Accept it to keep it.",
+                "tool_calls": []}
+    if last.name == "view_pages":
+        return {"content": "I looked at the rendered pages. (The demo agent can't judge images; a vision model "
+                           "would comment on spacing and overflow here.)", "tool_calls": []}
+    if last.name == "compile_references":
+        return {"content": "Here are the sources cited so far:\n\n" + last.content, "tool_calls": []}
+    if last.name == "get_document":
+        n = len(re.findall(r"^\d+\. \[blk_", last.content, re.MULTILINE))
+        return {"content": (f"(demo agent) I can see {n} block(s). Try: **address all comments**, "
+                            "**write a paragraph about <topic>**, **look at the layout**, or **list the references**."),
+                "tool_calls": []}
+    return {"content": "(demo agent) Done.", "tool_calls": []}
+
+
+def build_demo_agent() -> Any:
+    from langchain.agents import create_agent
+    from langchain_core.language_models import BaseChatModel
+    from langchain_core.messages import AIMessage
+    from langchain_core.outputs import ChatGeneration, ChatResult
+
+    class DemoCoauthorModel(BaseChatModel):
+        """Keyless scripted model (see :func:`demo_turn`)."""
+
+        @property
+        def _llm_type(self) -> str:
+            return "codraft-demo"
+
+        def bind_tools(self, tools, **kwargs):
+            return self
+
+        def _generate(self, messages, stop=None, run_manager=None, **kwargs):
+            turn = demo_turn(list(messages))
+            msg = AIMessage(content=turn["content"], tool_calls=turn["tool_calls"])
+            return ChatResult(generations=[ChatGeneration(message=msg)])
+
+    return create_agent(DemoCoauthorModel(), middleware=[CodraftMiddleware(attach_images=False)],
+                        name="codraft-demo")
+
+
+# ---------------------------------------------------------------------- resolution
+def resolve(cfg: Any, *, model: str | None = None) -> tuple[Any, dict]:
+    """(graph, info) for a resolved CodraftConfig. ``info`` feeds ``check`` and the UI."""
+    from langstage_core import load_agent_spec
+
+    if cfg.demo:
+        return build_demo_agent(), {"kind": "demo", "label": "Demo co-author (keyless)", "missing_tools": []}
+    if cfg.agent_spec:
+        obj = load_agent_spec(cfg.agent_spec, base_dir=cfg.toml_dir_for("agent_spec"))
+        graph, kind = resolve_agent_object(obj)
+        return graph, {"kind": kind, "label": cfg.agent_spec, "missing_tools": missing_tools(graph)}
+    spec = model or cfg.model or default_model_spec()
+    if not spec:
+        return None, {"kind": "none", "label": "No agent configured",
+                      "missing_tools": sorted(TOOL_NAMES),
+                      "hint": "Pass --agent path.py:graph, --model provider:model, set OPENROUTER_API_KEY "
+                              "or OPENAI_API_KEY, or run with --demo."}
+    return build_default_agent(spec), {"kind": "default", "label": spec, "missing_tools": []}
+
+
+def describe_info(info: dict) -> str:
+    return json.dumps(info, indent=2)

langstage_codraft/cli.py

@@ -0,0 +1,237 @@
+"""``langstage-codraft`` command line.
+
+    langstage-codraft run [--agent path.py:graph | --model provider:model | --demo]
+    langstage-codraft check [--live]
+    langstage-codraft new "Title" [--template report]
+    langstage-codraft list
+    langstage-codraft export DOC_ID --format pdf -o out.pdf   (needs a running server)
+    langstage-codraft install-browser
+"""
+from __future__ import annotations
+
+import json
+import sys
+import webbrowser
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .config import CodraftConfig
+
+
+def _cfg(**overrides) -> CodraftConfig:
+    return CodraftConfig.resolve(overrides=overrides)
+
+
+def _ok(msg: str) -> None:
+    click.echo(f"[ ok ] {msg}")
+
+
+def _warn(msg: str) -> None:
+    click.echo(f"[warn] {msg}")
+
+
+def _fail(msg: str) -> None:
+    click.echo(f"[fail] {msg}")
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(__version__, prog_name="langstage-codraft")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """Codraft: the document stage for your LangGraph agent."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+_agent_opts = [
+    click.option("-a", "--agent", "agent_spec", help="Agent spec, e.g. my_agent.py:graph (a graph or a factory)."),
+    click.option("-m", "--model", help="Model for the default agent, e.g. openrouter:anthropic/claude-haiku-5.5."),
+    click.option("--demo", is_flag=True, default=None, help="Run the keyless scripted demo co-author."),
+    click.option("--data-dir", type=click.Path(path_type=Path), help="Where documents, uploads and checkpoints live."),
+]
+
+
+def _with_agent_opts(f):
+    for opt in reversed(_agent_opts):
+        f = opt(f)
+    return f
+
+
+@main.command()
+@_with_agent_opts
+@click.option("--host", help="Bind address (default localhost).")
+@click.option("-p", "--port", type=int, help="Port (default 8060).")
+@click.option("--approval", type=click.Choice(["required", "auto"]), help="Default approval mode for new documents.")
+@click.option("--no-browser", is_flag=True, help="Don't open a browser tab.")
+@click.option("--show-config", is_flag=True, help="Print the resolved config and exit.")
+def run(agent_spec, model, demo, data_dir, host, port, approval, no_browser, show_config) -> None:
+    """Start the Codraft web app."""
+    cfg = _cfg(agent_spec=agent_spec, model=model, demo=demo, data_dir=data_dir, host=host, port=port,
+               approval=approval)
+    if show_config:
+        click.echo(cfg.describe())
+        return
+    from .agent import resolve
+    from .server import create_app
+
+    try:
+        graph, info = resolve(cfg)
+    except Exception as exc:  # noqa: BLE001
+        _fail(f"could not load the agent: {type(exc).__name__}: {exc}")
+        sys.exit(2)
+    if graph is None:
+        _warn(info.get("hint", "no agent configured; the editor works, chat is disabled"))
+    elif info.get("missing_tools"):
+        _warn(f"agent {info['label']} lacks codraft tools ({len(info['missing_tools'])} missing); it can chat "
+              "but cannot edit the document. Add CodraftMiddleware() or export a factory(tools, middleware).")
+    app = create_app(cfg, graph, info)
+    url = f"http://{cfg.host}:{cfg.port}"
+    click.echo(f"Codraft {__version__}  agent: {info.get('label')}  data: {Path(cfg.data_dir).resolve()}")
+    click.echo(f"Open {url}")
+    if not no_browser:
+        import threading
+
+        threading.Timer(1.2, lambda: webbrowser.open(url)).start()
+    import uvicorn
+
+    uvicorn.run(app, host=cfg.host, port=cfg.port, log_level="warning")
+
+
+@main.command()
+@_with_agent_opts
+@click.option("--live", is_flag=True, help="Also run one real agent turn (costs a model call).")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def check(agent_spec, model, demo, data_dir, live, as_json) -> None:
+    """Preflight: agent, tools, browser for export/vision, and (with --live) one real turn."""
+    cfg = _cfg(agent_spec=agent_spec, model=model, demo=demo, data_dir=data_dir)
+    from .agent import resolve
+
+    report: dict = {"version": __version__, "checks": []}
+
+    def add(name: str, ok: bool | None, detail: str) -> None:
+        report["checks"].append({"name": name, "ok": ok, "detail": detail})
+
+    graph = None
+    try:
+        graph, info = resolve(cfg)
+        if graph is None:
+            add("agent", False, info.get("hint", "no agent"))
+        else:
+            add("agent", True, f"{info['kind']}: {info['label']}")
+            missing = info.get("missing_tools") or []
+            add("tools", not missing, "all codraft tools present" if not missing
+                else f"missing {', '.join(missing)} (add CodraftMiddleware() or use a factory)")
+            add("checkpointer", True, "compiled-in" if getattr(graph, "checkpointer", None)
+                else "none compiled in; the server attaches a durable SQLite one")
+    except Exception as exc:  # noqa: BLE001
+        add("agent", False, f"{type(exc).__name__}: {exc}")
+
+    try:
+        from playwright.sync_api import sync_playwright
+
+        with sync_playwright() as p:
+            b = p.chromium.launch()
+            b.close()
+        add("browser", True, "Chromium available for export and view_pages")
+    except Exception as exc:  # noqa: BLE001
+        msg = str(exc).splitlines()[0][:160]
+        add("browser", None, f"not available ({msg}); run: langstage-codraft install-browser")
+
+    static = Path(__file__).parent / "static" / "index.html"
+    add("web-ui", static.is_file(), "bundled" if static.is_file() else "not built (cd frontend && npm run build)")
+
+    if live and graph is not None:
+        from langstage_core.agui import verify
+
+        from .store import Store, set_store
+
+        tmp = Path(cfg.data_dir) / "check"
+        store = Store(tmp / "check.db")
+        set_store(store)
+        doc = store.create_document("check", {})
+        res = verify(graph, message="Call get_document, then say OK.", thread_id=doc["id"])
+        add("live-turn", bool(res.ok), res.reason)
+
+    ok = all(c["ok"] is not False for c in report["checks"])
+    report["ok"] = ok
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+    else:
+        for c in report["checks"]:
+            (_ok if c["ok"] else _warn if c["ok"] is None else _fail)(f"{c['name']}: {c['detail']}")
+    sys.exit(0 if ok else 1)
+
+
+@main.command("list")
+@click.option("--data-dir", type=click.Path(path_type=Path))
+@click.option("--json", "as_json", is_flag=True)
+def list_docs(data_dir, as_json) -> None:
+    """List documents in the data directory."""
+    from .store import Store
+
+    cfg = _cfg(data_dir=data_dir)
+    docs = Store(Path(cfg.data_dir) / "codraft.db").list_documents()
+    if as_json:
+        click.echo(json.dumps(docs, indent=2))
+        return
+    if not docs:
+        click.echo("No documents yet.")
+    for d in docs:
+        click.echo(f"{d['id']}  {d['title']}  ({d['n_blocks']} blocks)")
+
+
+@main.command()
+@click.argument("title")
+@click.option("--template", default="blank", help="Template id (see the new-document dialog).")
+@click.option("--data-dir", type=click.Path(path_type=Path))
+def new(title, template, data_dir) -> None:
+    """Create a document from a template."""
+    from . import templates as tpl
+    from .store import Store
+
+    cfg = _cfg(data_dir=data_dir)
+    tpl.configure(cfg.templates_dir)
+    t = tpl.all_templates().get(template)
+    if t is None:
+        _fail(f"unknown template {template!r}; available: {', '.join(tpl.all_templates())}")
+        sys.exit(2)
+    store = Store(Path(cfg.data_dir) / "codraft.db")
+    doc = store.create_document(title, {"approval": cfg.approval, "theme": cfg.default_theme,
+                                        **t.get("settings", {})}, t.get("blocks", []))
+    click.echo(doc["id"])
+
+
+@main.command()
+@click.argument("doc_id")
+@click.option("-f", "--format", "fmt", type=click.Choice(["pdf", "png", "jpg", "html"]), default="pdf")
+@click.option("-o", "--output", type=click.Path(path_type=Path))
+@click.option("--url", default=None, help="Server URL (default http://localhost:<port>).")
+def export(doc_id, fmt, output, url) -> None:
+    """Export a document through a running Codraft server."""
+    import httpx
+
+    cfg = _cfg()
+    base = url or f"http://{cfg.host}:{cfg.port}"
+    r = httpx.get(f"{base}/api/docs/{doc_id}/export", params={"format": fmt}, timeout=180)
+    if r.status_code != 200:
+        _fail(f"{r.status_code}: {r.text[:300]}")
+        sys.exit(1)
+    disp = r.headers.get("content-disposition", "")
+    name = disp.split("filename=")[-1].strip('"') if "filename=" in disp else f"{doc_id}.{fmt}"
+    out = output or Path(name)
+    out.write_bytes(r.content)
+    _ok(f"wrote {out} ({len(r.content)} bytes)")
+
+
+@main.command("install-browser")
+def install_browser_cmd() -> None:
+    """Download Chromium for export and the agent's view_pages tool."""
+    from .render import install_browser
+
+    sys.exit(install_browser())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

langstage_codraft/config.py

@@ -0,0 +1,58 @@
+"""Codraft configuration: the family's ``HostConfig`` chain plus a ``[codraft]`` table.
+
+Precedence (lowest to highest): defaults < ``langstage.toml`` < ``LANGSTAGE_*`` env <
+CLI flags, exactly as on every other LangStage surface.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from langstage_core import HostConfig
+
+
+def _env_bool(v: str) -> bool:
+    return v.strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass
+class CodraftConfig(HostConfig):
+    port: int = 8060
+    title: str = "Codraft"
+    model: str | None = None              # e.g. "openrouter:anthropic/claude-haiku-5.5", "openai:gpt-4.1-mini"
+    approval: str = "required"            # default approval mode for new documents
+    data_dir: Path = Path(".codraft")     # SQLite store, uploads, checkpoints, renders
+    templates_dir: Path | None = None
+    default_theme: str = "classic"
+    demo: bool = False
+
+    _ENV: ClassVar[dict] = {
+        "model": ("LANGSTAGE_CODRAFT_MODEL", str),
+        "approval": ("LANGSTAGE_CODRAFT_APPROVAL", str),
+        "data_dir": ("LANGSTAGE_CODRAFT_DATA_DIR", Path),
+        "templates_dir": ("LANGSTAGE_CODRAFT_TEMPLATES_DIR", Path),
+        "default_theme": ("LANGSTAGE_CODRAFT_THEME", str),
+        "demo": ("LANGSTAGE_CODRAFT_DEMO", _env_bool),
+    }
+    _TOML: ClassVar[dict] = {
+        "model": "codraft.model",
+        "approval": "codraft.approval",
+        "data_dir": "codraft.data_dir",
+        "templates_dir": "codraft.templates_dir",
+        "default_theme": "codraft.default_theme",
+        "demo": "codraft.demo",
+    }
+    _TOML_PATHS: ClassVar[dict] = {"data_dir": "path", "templates_dir": "path"}
+
+
+def codraft_toml_table() -> dict[str, Any]:
+    """The raw ``[codraft]`` table (themes and the allowed list live there)."""
+    try:
+        from langstage_core.host.config import load_toml_config
+
+        data, _ = load_toml_config()
+    except Exception:  # noqa: BLE001 - a malformed TOML is reported by describe()
+        return {}
+    t = data.get("codraft", {})
+    return t if isinstance(t, dict) else {}