v0.9.7: a turn that cannot hang, a session list that reads nothing twice, and PDFs

- consent: on_permission / on_ask_user wait at most two / five minutes, and in
  the background (a phone off screen, a window that is gone) the answer is
  refused at once with a reason -- a dialog nobody can see blocked the worker
  for good, which is what "the app hangs while the agent works" looked like.
- finishTurn() no longer joins the thread it is called from; the event loop
  reaps the Turn instead.
- AndroidTools: the hop to the GUI thread pings first and gives up after 3 s
  instead of waiting forever on a busy GUI thread.
- the session list stopped reading every transcript: cst_agent_store_info()
  counts newlines in 64 KiB blocks (first_user only within the first 256 KiB),
  and AgentCore::sessions() reuses a row while (mtime, size) is unchanged.
- session_search gets a budget (max_bytes 32 MB, max_seconds 5 s), skips lines
  over 64 KiB, and says when the budget stopped the walk.
- the header shows the phase ("shell: make -j8"), so a long turn no longer
  looks like a stuck one.
- md_to_pdf: the front end's own Qt tool (owner app:qt, every platform):
  markdown or a workspace .md/.html becomes an A4 PDF with 15 mm margins,
  paginated by hand, written into the workspace and delivered as a file card.
  No PrintSupport, so the phone gets it too.
- --uitest runs md_to_pdf through the registry with Chinese text and checks the
  bytes are a PDF; app/CMakeLists.txt no longer drops src/web_md.c from the
  standalone engine build, which the window needs to render markdown.

Version 0.9.7.

app/src/core/AgentCore.cpp

@@ -189,6 +189,12 @@ void AgentCore::close() {
 /* --- turns --------------------------------------------------------------- */
 
 namespace {
+/* How long the worker waits for a person. Long enough to read a file diff and
+ * decide, short enough that a missed dialog (or a screen that went dark) does
+ * not leave the turn waiting for good. */
+constexpr int kConsentTimeoutMs = 2 * 60 * 1000;
+constexpr int kQuestionTimeoutMs = 5 * 60 * 1000;
+
 /* The first line of a prompt, cut short: the line the phone's "working"
  * notification carries while the turn runs (app::holdForeground). */
 QString firstLine(const QString &s) {
@@ -224,9 +230,28 @@ void AgentCore::cancel() {
     cst_agent_request_cancel(m_agent);
 }
 
+/* Qt suspends the application when the phone puts it away, and a desktop
+ * window can be gone too (--uitest runs headless). Either way a consent
+ * dialog would be invisible. */
+bool AgentCore::backgrounded() const {
+  QGuiApplication *gui =
+      qobject_cast<QGuiApplication *>(QCoreApplication::instance());
+  if (!gui)
+    return false;
+  if (gui->applicationState() == Qt::ApplicationSuspended)
+    return true;
+  return gui->allWindows().isEmpty() && gui->topLevelWindows().isEmpty();
+}
+
 void AgentCore::finishTurn(int rc, const QString &err) {
   Turn *t = static_cast<Turn *>(sender());
+  if (t) {
+    /* run() is the caller: waiting for the thread here would be waiting for
+     * this very call to return. Let the event loop reap it instead. */
+    connect(t, &QThread::finished, t, &QObject::deleteLater);
+  }
   post([this, rc, err] {
+    m_turn = nullptr;
     setRunning(false);
     app::releaseForeground(); /* the turn is over: let the phone sleep again */
     /* The prompt carried whatever was pending; the engine dropped it. */
@@ -234,11 +259,6 @@ void AgentCore::finishTurn(int rc, const QString &err) {
     emit pendingChanged();
     emit turnFinished(rc, err);
   });
-  if (t) {
-    t->wait();
-    t->deleteLater();
-  }
-  m_turn = nullptr;
 }
 
 void AgentCore::setRunning(bool on) {
@@ -275,16 +295,43 @@ int AgentCore::hookPermission(const char *tool, const char *detail,
     return CST_PERM_DENY;
   if (self->m_autoApprove)
     return CST_PERM_ONCE;
+  const QString t = QString::fromUtf8(tool ? tool : "");
+  /* The turn survives the app leaving the screen (v0.9.4), so a question
+   * asked there would block the worker on a dialog nobody can see -- which is
+   * what "the app hangs while the agent works" looks like. In the background
+   * the answer is no, with a line the person finds in the transcript. */
+  if (self->backgrounded()) {
+    self->post([self, t] {
+      emit self->permissionExpired(t);
+      emit self->statusChanged(
+          QStringLiteral("%1: refused — the app was in the background").arg(t));
+    });
+    return CST_PERM_DENY;
+  }
   QMutexLocker lock(&self->m_askMu);
   self->m_permAnswer = CST_PERM_DENY;
   self->m_permPending = true;
-  const QString t = QString::fromUtf8(tool ? tool : "");
   const QString d = QString::fromUtf8(detail ? detail : "");
   const QString p = QString::fromUtf8(preview ? preview : "");
   self->post([self, t, d, p] { emit self->permissionRequested(t, d, p); });
-  while (self->m_permPending && !self->m_closing)
-    self->m_askCv.wait(&self->m_askMu);
+  /* And even in the foreground nobody may hang forever: a dialog can be
+   * missed, a screen can go dark. Two minutes, then the answer is no. */
+  bool expired = false;
+  while (self->m_permPending && !self->m_closing) {
+    if (!self->m_askCv.wait(&self->m_askMu, kConsentTimeoutMs)) {
+      expired = true;
+      break;
+    }
+  }
   self->m_permPending = false;
+  if (expired) {
+    self->post([self, t] {
+      emit self->permissionExpired(t);
+      emit self->statusChanged(
+          QStringLiteral("%1: no answer for two minutes — refused").arg(t));
+    });
+    return CST_PERM_DENY;
+  }
   return self->m_permAnswer;
 }
 
@@ -295,16 +342,40 @@ int AgentCore::hookAskUser(const char *question, const char *options, char *ans,
     return -1;
   if (self->m_autoApprove)
     return -1;
+  if (self->backgrounded()) {
+    self->post([self] {
+      emit self->questionExpired();
+      emit self->statusChanged(
+          QStringLiteral("the question was dropped — the app was in the "
+                         "background"));
+    });
+    return -1;
+  }
   QMutexLocker lock(&self->m_askMu);
   self->m_questionPending = true;
   self->m_answer.clear();
   const QString q = QString::fromUtf8(question ? question : "");
   const QString o = QString::fromUtf8(options ? options : "");
   self->post([self, q, o] { emit self->questionAsked(q, o); });
-  while (self->m_questionPending && !self->m_closing)
-    self->m_askCv.wait(&self->m_askMu);
+  bool expired = false;
+  while (self->m_questionPending && !self->m_closing) {
+    if (!self->m_askCv.wait(&self->m_askMu, kQuestionTimeoutMs)) {
+      expired = true;
+      break;
+    }
+  }
   if (self->m_closing)
     return -1;
+  self->m_questionPending = false;
+  if (expired) {
+    self->post([self] {
+      emit self->questionExpired();
+      emit self->statusChanged(
+          QStringLiteral("no answer for five minutes — the question was "
+                         "dropped"));
+    });
+    return -1;
+  }
   snprintf(ans, ans_sz, "%s", self->m_answer.constData());
   return 0;
 }
@@ -530,29 +601,56 @@ QString AgentCore::shareArtifact(const QString &rel) {
 
 QVariantList AgentCore::sessions() const {
   QVariantList out;
-  if (m_workspace.isEmpty())
+  if (m_workspace.isEmpty()) {
+    m_sessionCache.clear();
     return out;
+  }
   const QByteArray ws = m_workspace.toUtf8();
   const int kMax = 200;
   char(*ids)[128] = new char[kMax][128];
   const int n = cst_agent_store_list(ws.constData(), ids, kMax);
   const QString current = sessionId();
+  QHash<QString, SessionCache> fresh;
+  fresh.reserve(n);
   for (int i = 0; i < n; i++) {
-    cst_session_info_t in;
-    memset(&in, 0, sizeof(in));
-    if (cst_agent_store_info(ws.constData(), ids[i], &in) != 0)
-      continue;
-    const QString id = utf8(in.id[0] ? in.id : ids[i]);
-    QVariantMap m;
-    m["id"] = id;
-    m["title"] = utf8(in.title);
-    m["firstUser"] = utf8(in.first_user);
-    m["messages"] = in.messages;
-    m["mtime"] = static_cast<qlonglong>(in.mtime) * 1000; /* ms, for JS Date */
+    const QString id = utf8(ids[i]);
+    /* Filling one row walks that session's whole transcript, and the sidebar
+     * asks for the list on every store change: the transcript's own stat is
+     * what tells "nothing happened to this one" from "it grew", so an
+     * unchanged session costs a stat instead of a read. */
+    char path[4096] = "";
+    const bool have_path = cst_agent_store_path_for_id(
+                               ws.constData(), ids[i], path, sizeof(path)) == 0;
+    const QFileInfo fi(have_path ? QString::fromUtf8(path) : QString());
+    const qint64 mtime = fi.lastModified().toSecsSinceEpoch();
+    const qint64 size = fi.size();
+    SessionCache entry;
+    const auto cached = m_sessionCache.constFind(id);
+    if (cached != m_sessionCache.constEnd() && cached->mtime == mtime &&
+        cached->size == size) {
+      entry = *cached;
+    } else {
+      cst_session_info_t in;
+      memset(&in, 0, sizeof(in));
+      if (cst_agent_store_info(ws.constData(), ids[i], &in) != 0)
+        continue;
+      entry.mtime = mtime;
+      entry.size = size;
+      QVariantMap m;
+      m["id"] = id;
+      m["title"] = utf8(in.title);
+      m["firstUser"] = utf8(in.first_user);
+      m["messages"] = in.messages;
+      m["mtime"] = static_cast<qlonglong>(in.mtime) * 1000; /* ms, for JS Date */
+      entry.row = m;
+    }
+    QVariantMap m = entry.row;
     m["current"] = (id == current);
     out.append(m);
+    fresh.insert(id, entry);
   }
   delete[] ids;
+  m_sessionCache = fresh; /* and the ids that are gone are forgotten */
   return out;
 }
 
@@ -710,6 +808,9 @@ bool AgentCore::deleteSession(const QString &id) {
 bool AgentCore::renameSession(const QString &id, const QString &title) {
   if (id.isEmpty() || m_workspace.isEmpty())
     return false;
+  /* A title is not in the transcript, so the cached rows would not notice the
+   * rename: drop them and let the next list read them again. */
+  m_sessionCache.clear();
   const QByteArray ws = m_workspace.toUtf8(), sid = id.toUtf8(),
                    t = title.toUtf8();
   if (cst_agent_store_title_set(ws.constData(), sid.constData(), t.constData()) !=
@@ -1138,7 +1239,20 @@ void AgentCore::hookToolEvent(const char *phase, const ctl_tool_call_t *call,
   const QString id = QString::fromUtf8(call && call->id ? call->id : "");
   const QString n = QString::fromUtf8(call ? call->name : "");
   const QString d = QString::fromUtf8(detail ? detail : "");
-  self->post([self, p, id, n, d] { emit self->toolEvent(p, id, n, d); });
+  self->post([self, p, id, n, d] {
+    emit self->toolEvent(p, id, n, d);
+    /* The header says what the turn is doing right now ("shell: make -j8"),
+     * not just that something is happening: a long turn is otherwise
+     * indistinguishable from a stuck one. */
+    if (p == QLatin1String("done")) {
+      emit self->statusChanged(QString());
+      return;
+    }
+    QString what = d;
+    if (what.size() > 80)
+      what = what.left(79) + QStringLiteral("…");
+    emit self->statusChanged(what.isEmpty() ? n : QStringLiteral("%1: %2").arg(n, what));
+  });
 }
 
 void AgentCore::hookToolResult(const ctl_tool_call_t *call, const char *out,

app/src/core/AgentCore.h

@@ -9,6 +9,7 @@
 #define CST_APP_AGENTCORE_H
 
 #include <QByteArray>
+#include <QHash>
 #include <QMutex>
 #include <QObject>
 #include <QString>
@@ -204,6 +205,11 @@ class AgentCore : public QObject {
   void permissionRequested(const QString &tool, const QString &detail,
                            const QString &preview);
   void questionAsked(const QString &question, const QString &options);
+  /* The worker asked and nobody answered in time (or the app was in the
+   * background, where the dialog cannot be seen): the turn went on with a
+   * refusal, and the window puts its dialog away again. */
+  void permissionExpired(const QString &tool);
+  void questionExpired();
   void turnFinished(int rc, const QString &err);
   void runningChanged();
   void workspaceChanged();
@@ -218,6 +224,10 @@ class AgentCore : public QObject {
   void syncConfig();
   /* Re-read what a session switch changed (id, todo) and say so. */
   void afterSessionChange();
+  /* True when the app is not on screen: a phone in the background (Qt
+   * suspends it), or a window that is not there at all. A dialog opened now
+   * would be invisible, so consent is refused instead of waited for. */
+  bool backgrounded() const;
 
   /* Hook trampolines (C, run on the worker thread). */
   static void hookStatus(const char *msg, void *ud);
@@ -255,6 +265,15 @@ class AgentCore : public QObject {
   bool m_permPending = false;
   QString m_question;
   QString m_todo;
+  /* The session list rebuilt only when a transcript moved: filling one row
+   * walks the whole file, and the sidebar asks for the list on every store
+   * change. Keyed by id, dropped when the id is gone. */
+  struct SessionCache {
+    qint64 mtime = 0;
+    qint64 size = 0;
+    QVariantMap row;
+  };
+  mutable QHash<QString, SessionCache> m_sessionCache;
   /* Names of the files this window attached, in the engine's pending order:
    * the engine's own description says what it is, not where it came from. */
   QStringList m_attachNames;

app/src/core/PdfTools.cpp

@@ -0,0 +1,315 @@
+/* The window's own tools, in Qt rather than in the engine: a document the
+ * person asked for, laid out as a PDF.
+ *
+ * Why here and not in the C engine: laying text out on pages is exactly what
+ * Qt does (QTextDocument + QPdfWriter, both in QtGui, which the app already
+ * links), while the engine has no layout code at all -- and md_to_html, its
+ * sibling, lives in the engine because rendering markdown is a shared
+ * capability. This one is a front-end capability: it is registered under
+ * owner "app:qt" and is available on every platform the app runs on.
+ *
+ * The path of a document is the one md_to_html walks: markdown (or a
+ * workspace .md/.html file) -> cst_web_md_document() -> a file inside the
+ * workspace -> cst_attach_import_artifact(), which is what turns it into a
+ * file card the person can open or share. The bytes never reach the model.
+ *
+ * Pagination is ours on purpose: QPrinter/PrintSupport is a desktop-only
+ * module (a phone has no print subsystem), and a round of
+ * pageSize + translate + drawContents per page is all a paginated PDF needs.
+ * The tool runs on the turn's worker thread, so a long document does not
+ * freeze the window. */
+
+#include <QByteArray>
+#include <QDir>
+#include <QFile>
+#include <QFileInfo>
+#include <QMarginsF>
+#include <QPageLayout>
+#include <QPageSize>
+#include <QPainter>
+#include <QPdfWriter>
+#include <QRectF>
+#include <QString>
+#include <QTextDocument>
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+#include "core/AgentCore.h"
+#include "core/ToolProvider.h"
+#include "cst_agent.h"
+#include "cst_attach.h"
+#include "cst_tools.h"
+#include "cst_web_md.h"
+
+namespace app {
+namespace {
+
+/* md_to_html caps its input the same way: a document nobody could read is
+ * not worth laying out. */
+constexpr int kMaxInputBytes = 8 * 1024 * 1024;
+/* 150 dpi: crisp enough for text, and a good deal lighter on a phone than the
+ * default 300 (a 40-page document is laid out and written in a moment). */
+constexpr int kPdfDpi = 150;
+
+const char *argOf(const ctl_tool_call_t *call, const char *key) {
+  for (int i = 0; i < call->nargs; i++)
+    if (strcmp(call->args[i].key, key) == 0)
+      return call->args[i].value;
+  return nullptr;
+}
+
+int setOut(cst_tool_result_t *r, const QString &text, int rc) {
+  const QByteArray b = text.toUtf8();
+  r->out = strdup(b.constData());
+  r->out_len = r->out ? strlen(r->out) : 0;
+  r->exit_code = rc;
+  return rc;
+}
+
+/* "docs/notes.md" -> "notes". */
+QString stemOf(const QString &path) {
+  QString base = path;
+  const int slash = qMax(base.lastIndexOf(QLatin1Char('/')),
+                         base.lastIndexOf(QLatin1Char('\\')));
+  if (slash >= 0)
+    base = base.mid(slash + 1);
+  const int dot = base.lastIndexOf(QLatin1Char('.'));
+  if (dot > 0)
+    base = base.left(dot);
+  return base.isEmpty() ? QStringLiteral("document") : base;
+}
+
+/* What the file is called: `out` when given (a directory takes the source's
+ * name inside it), otherwise the source's stem, or the title. */
+QString outPathOf(const ctl_tool_call_t *c, const QString &stem) {
+  const char *out = argOf(c, "out");
+  QString name = out && out[0] ? QString::fromUtf8(out) : QString();
+  if (name.isEmpty())
+    return stem + QStringLiteral(".pdf");
+  if (name.endsWith(QLatin1Char('/')) || name.endsWith(QLatin1Char('\\')))
+    return name + stem + QStringLiteral(".pdf");
+  if (!QFileInfo(name).fileName().contains(QLatin1Char('.')))
+    name += QStringLiteral(".pdf");
+  return name;
+}
+
+/* The HTML that goes into the page: an .html file is already a document, a
+ * .md file (or the `markdown` argument) goes through the engine's renderer,
+ * which is the same one the WebUI and md_to_html use. */
+bool sourceHtml(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                QString *html, QString *out_name, QString *err) {
+  const char *md = argOf(c, "markdown");
+  const char *file = argOf(c, "file");
+  const char *given = argOf(c, "title");
+  QString title = given && given[0] ? QString::fromUtf8(given) : QString();
+  QByteArray text;
+  QString stem;
+  if (file && file[0]) {
+    char rel[4096] = "";
+    if (cst_sandbox_resolve(ctx->workspace_root, file, rel, sizeof(rel)) != 0) {
+      *err = QStringLiteral("error: path outside the workspace or missing "
+                            "parent: %1")
+                 .arg(QString::fromUtf8(file));
+      return false;
+    }
+    QFile in(QString::fromUtf8(rel));
+    if (!in.open(QIODevice::ReadOnly)) {
+      *err = QStringLiteral("error: cannot read %1")
+                 .arg(QString::fromUtf8(file));
+      return false;
+    }
+    if (in.size() > kMaxInputBytes) {
+      *err = QStringLiteral("error: %1 is larger than %2 MB")
+                 .arg(QString::fromUtf8(file))
+                 .arg(kMaxInputBytes >> 20);
+      return false;
+    }
+    text = in.readAll();
+    stem = stemOf(QString::fromUtf8(file));
+    const QString lower = QString::fromUtf8(file).toLower();
+    if (lower.endsWith(QLatin1String(".html")) ||
+        lower.endsWith(QLatin1String(".htm"))) {
+      /* already a document: what md_to_html wrote, or anything else */
+      *html = QString::fromUtf8(text);
+      if (title.isEmpty())
+        title = stem;
+      *out_name = outPathOf(c, stem);
+      return true;
+    }
+  } else if (md && md[0]) {
+    text = QByteArray(md);
+    if (stem.isEmpty())
+      stem = title.isEmpty() ? QStringLiteral("document") : stemOf(title);
+  } else {
+    *err = QStringLiteral("error: give markdown, or a workspace .md or .html "
+                          "file to render");
+    return false;
+  }
+  if (title.isEmpty())
+    title = stem;
+  char *doc =
+      cst_web_md_document(text.constData(), static_cast<size_t>(text.size()),
+                          title.toUtf8().constData());
+  if (!doc) {
+    *err = QStringLiteral("error: cannot render the markdown");
+    return false;
+  }
+  *html = QString::fromUtf8(doc);
+  free(doc);
+  *out_name = outPathOf(c, stem);
+  return true;
+}
+
+/* Write `html` into `path` as an A4 PDF with 15 mm margins: one page rect,
+ * translated down per page, and the document is asked for exactly that much
+ * text at a time -- which is what makes Qt lay out pages instead of one long
+ * strip. */
+bool writePdf(const QString &html, const QString &path, const QString &title,
+              QString *err) {
+  QTextDocument doc;
+  doc.setHtml(html);
+  if (!title.isEmpty())
+    doc.setMetaInformation(QTextDocument::DocumentTitle, title);
+
+  QPdfWriter writer(path);
+  writer.setPageSize(QPageSize(QPageSize::A4));
+  writer.setPageMargins(QMarginsF(15, 15, 15, 15), QPageLayout::Millimeter);
+  writer.setResolution(kPdfDpi);
+  if (!title.isEmpty())
+    writer.setTitle(title);
+
+  QPainter painter(&writer);
+  if (!painter.isActive()) {
+    *err = QStringLiteral("error: cannot draw into %1").arg(path);
+    return false;
+  }
+  const QRectF page = writer.pageLayout().paintRectPixels(writer.resolution());
+  doc.setPageSize(page.size());
+  const int pages = qMax(1, doc.pageCount());
+  for (int i = 0; i < pages; i++) {
+    if (i)
+      writer.newPage();
+    painter.save();
+    painter.translate(page.topLeft());
+    painter.translate(0, -i * page.height());
+    doc.drawContents(&painter,
+                     QRectF(0, 0, page.width(), page.height())
+                         .translated(0, i * page.height()));
+    painter.restore();
+  }
+  painter.end();
+  /* The painter says nothing about the file: the only proof the PDF landed is
+   * that there is one with bytes in it. */
+  if (QFileInfo(path).size() <= 0) {
+    *err = QStringLiteral("error: nothing was written to %1").arg(path);
+    return false;
+  }
+  return true;
+}
+
+int mdToPdfPreview(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                   char **out) {
+  (void)ctx;
+  const char *md = argOf(c, "markdown");
+  const char *file = argOf(c, "file");
+  if ((!md || !md[0]) && (!file || !file[0])) {
+    *out = strdup("error: give markdown, or a .md or .html file to render");
+    return -1;
+  }
+  const QString stem =
+      file && file[0] ? stemOf(QString::fromUtf8(file)) : QStringLiteral("document");
+  const QString name = outPathOf(c, stem);
+  QByteArray line;
+  if (file && file[0])
+    line = QStringLiteral("lay out %1 → %2 as a PDF\n")
+               .arg(QString::fromUtf8(file), name)
+               .toUtf8();
+  else
+    line = QStringLiteral("lay out %1 bytes of markdown → %2 as a PDF\n")
+               .arg(md ? qstrlen(md) : 0)
+               .arg(name)
+               .toUtf8();
+  *out = strdup(line.constData());
+  return 0;
+}
+
+int mdToPdfRun(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+               cst_tool_result_t *r, void *ud) {
+  (void)ud;
+  QString html, out_name, err;
+  if (!sourceHtml(ctx, c, &html, &out_name, &err))
+    return setOut(r, err, 1);
+
+  char full[4096] = "";
+  if (cst_sandbox_resolve(ctx->workspace_root, out_name.toUtf8().constData(),
+                          full, sizeof(full)) != 0)
+    return setOut(r, QStringLiteral("error: path outside the workspace: %1")
+                         .arg(out_name),
+                  1);
+  const QString target = QString::fromUtf8(full);
+  /* A directory in the way of the name is what the engine's write tools call
+   * "missing parent": make it, the same way md_to_html does. */
+  QDir().mkpath(QFileInfo(target).absolutePath());
+
+  const char *given = argOf(c, "title");
+  const QString title = given && given[0] ? QString::fromUtf8(given) : QString();
+  if (!writePdf(html, target, title, &err))
+    return setOut(r, err, 1);
+
+  const qint64 bytes = QFileInfo(target).size();
+  const char *session = ctx->agent ? cst_agent_session_path(ctx->agent) : nullptr;
+  cst_attachment_t *a = nullptr;
+  char aerr[256] = "";
+  if (session && session[0])
+    a = cst_attach_import_artifact(session, full, nullptr, aerr, sizeof(aerr));
+
+  QString text = QStringLiteral("wrote %1 (%2 KB, A4, 15 mm margins)\n")
+                     .arg(out_name)
+                     .arg(bytes / 1024);
+  if (a)
+    text += QStringLiteral("(the user sees it as a file card they can open or "
+                           "share; you will not be shown its bytes again)\n");
+  else if (aerr[0])
+    text += QStringLiteral("(the file is in the workspace; handing it over "
+                           "failed: %1)\n")
+                .arg(QString::fromUtf8(aerr));
+  const int rc = setOut(r, text, 0);
+  if (a) {
+    r->attach = a;
+    r->nattach = 1;
+  }
+  return rc;
+}
+
+}  // namespace
+
+int registerQtTools(AgentCore *core) {
+  if (!core)
+    return 0;
+  static const cst_tool_param_t params[CST_TOOL_MAX_PARAMS] = {
+      {"markdown", "string", 0, "markdown text to render"},
+      {"file", "string", 0,
+       "workspace .md file to render, or an .html one to lay out as it is"},
+      {"out", "string", 0,
+       "output path in the workspace (default: the source's name + .pdf)"},
+      {"title", "string", 0, "document title (default: the file name)"},
+      {nullptr, nullptr, 0, nullptr},
+      {nullptr, nullptr, 0, nullptr}};
+  static cst_tool_def_t def;
+  memset(&def, 0, sizeof(def));
+  setMeta(&def, "md_to_pdf",
+          "Write a document as a PDF: markdown (or a workspace .md/.html "
+          "file) in, a laid-out A4 PDF out, saved in the workspace and "
+          "handed to the person as a card they can open, print or share. "
+          "Use it when the answer should be something to keep or send.",
+          CST_TP_WRITE, "pdf", nullptr, nullptr);
+  memcpy(def.params, params, sizeof(params));
+  def.run_ex = mdToPdfRun;
+  def.preview = mdToPdfPreview;
+  def.owner = "app:qt";
+  return core->registerTool(&def) ? 1 : 0;
+}
+
+}  // namespace app

app/src/core/ToolProvider.cpp

@@ -22,6 +22,8 @@ int registerPlatformTools(AgentCore *core) {
 #elif defined(__linux__)
   n += platformRegisterLinux(core);
 #endif
+  /* Qt is not a platform API: these exist wherever the window does. */
+  n += registerQtTools(core);
   /* A service may have appeared or gone since the last probe (a desktop
    * session starting, the notification daemon coming up). */
   cst_tool_meta_reload();
@@ -35,6 +37,7 @@ void unregisterPlatformTools(AgentCore *core) {
   core->unregisterOwner(QStringLiteral("app:windows"));
   core->unregisterOwner(QStringLiteral("app:macos"));
   core->unregisterOwner(QStringLiteral("app:android"));
+  core->unregisterOwner(QStringLiteral("app:qt"));
 }
 
 }  // namespace app

app/src/core/ToolProvider.h

@@ -44,6 +44,10 @@ extern const char *const kDesktopOnly[];
 /* The platform tools this app provides. Called once the engine exists;
  * returns how many were registered. */
 int registerPlatformTools(AgentCore *core);
+/* The tools this front end provides that are the same on every platform
+ * (they are Qt, not a platform API): today md_to_pdf, owned by "app:qt".
+ * Called next to registerPlatformTools(). */
+int registerQtTools(AgentCore *core);
 /* Drop them again (they belong to the owners "app:*"). */
 void unregisterPlatformTools(AgentCore *core);
 

app/src/platform/android/AndroidTools.cpp

@@ -27,6 +27,7 @@
 #include <QGuiApplication>
 #include <QJniObject>
 #include <QMetaObject>
+#include <QSemaphore>
 #include <QStandardPaths>
 #include <QString>
 #include <QStringList>
@@ -36,6 +37,7 @@
 
 #include <cstdio>
 #include <cstring>
+#include <memory>
 #include <utility>
 
 #include "core/AgentCore.h"
@@ -59,16 +61,34 @@ void setOut(cst_tool_result_t *r, const QByteArray &text, int rc) {
   r->exit_code = rc;
 }
 
+/* How long the worker is willing to wait for the GUI thread to pick its work
+ * up. The hop itself is always waited for to the end (the closure writes into
+ * the caller's stack), so what this bounds is the case that makes a turn look
+ * stuck: a GUI thread that is not getting to the event loop at all. */
+constexpr int kGuiStallMs = 3000;
+
 /* Anything that touches a Qt GUI object (the clipboard) or an Activity has to
- * run on the GUI thread; the turn's worker thread waits for it. */
+ * run on the GUI thread; the turn's worker thread waits for it.
+ *
+ * The wait is bounded: a blocking queued call to a GUI thread that is busy
+ * (the session list reading transcripts used to do exactly that) would park
+ * the worker for as long as it lasts. A cheap ping first tells whether the
+ * GUI thread is there at all; only then is the real work handed over and
+ * waited for, which keeps the closure valid for its whole life. */
 template <typename Fn>
-void onGuiThread(Fn &&fn) {
+bool onGuiThread(Fn &&fn) {
   if (!qApp || QThread::currentThread() == qApp->thread()) {
     fn();
-    return;
+    return true;
   }
+  auto pinged = std::make_shared<QSemaphore>(0);
+  QMetaObject::invokeMethod(qApp, [pinged] { pinged->release(); },
+                            Qt::QueuedConnection);
+  if (!pinged->tryAcquire(1, kGuiStallMs))
+    return false; /* a GUI thread that is not answering: do not wait on it */
   QMetaObject::invokeMethod(qApp, std::forward<Fn>(fn),
                             Qt::BlockingQueuedConnection);
+  return true;
 }
 
 jint sdkInt() {

app/src/ui/UiTest.cpp

@@ -416,6 +416,53 @@ int runUiTest(AgentCore &core, const QString &size) {
           QStringLiteral("and the line is where the card is"));
   }
 
+  /* --- md_to_pdf: the front end's own document writer ------------------- */
+  {
+    const cst_tool_def_t *def = cst_tool_find("md_to_pdf");
+    check(def != nullptr && def->owner != nullptr &&
+              strncmp(def->owner, "app:qt", 6) == 0,
+          QStringLiteral("md_to_pdf is registered by the front end"));
+    if (def && def->run_ex) {
+      /* Run it the way the agent's turn would: through the registry, with a
+       * call and the engine's context. */
+      const QByteArray ws = core.workspace().toUtf8();
+      cst_tool_ctx_t ctx;
+      memset(&ctx, 0, sizeof(ctx));
+      ctx.workspace_root = ws.constData();
+      ctx.agent = core.agent();
+      ctl_tool_call_t call;
+      memset(&call, 0, sizeof(call));
+      snprintf(call.id, sizeof(call.id), "pdf1");
+      snprintf(call.name, sizeof(call.name), "md_to_pdf");
+      static const char *kMd =
+          "# 设备信息报告\n\n这是一段**中文**正文，用来确认字体和分页。\n\n"
+          "- 项目一\n- 项目二\n\n```\ncode block\n```\n";
+      static const char *kOut = "selftest.pdf";
+      snprintf(call.args[0].key, sizeof(call.args[0].key), "markdown");
+      call.args[0].value = const_cast<char *>(kMd);
+      call.args[0].value_len = strlen(kMd);
+      snprintf(call.args[1].key, sizeof(call.args[1].key), "out");
+      call.args[1].value = const_cast<char *>(kOut);
+      call.args[1].value_len = strlen(kOut);
+      call.nargs = 2;
+      cst_tool_result_t res;
+      memset(&res, 0, sizeof(res));
+      const int rc = cst_tool_run(&ctx, &call, &res);
+      check(res.exit_code == 0,
+            QStringLiteral("md_to_pdf writes the document (%1)")
+                .arg(QString::fromUtf8(res.out ? res.out : "")));
+      check(rc == 0 && res.nattach == 1,
+            QStringLiteral("and hands it over as a file for the user"));
+      QFile f(core.workspace() + QStringLiteral("/selftest.pdf"));
+      const bool opened = f.open(QIODevice::ReadOnly);
+      const QByteArray head = opened ? f.read(5) : QByteArray();
+      check(head == QByteArrayLiteral("%PDF-"),
+            QStringLiteral("the bytes are a PDF (%1)")
+                .arg(QString::fromLatin1(head)));
+      cst_tool_result_free(&res);
+    }
+  }
+
   /* new sessions: the engine moves, the view empties, the store grows */
   const int before = core.sessions().size();
   clickMouse(win, QStringLiteral("newSessionButton"));