From 02821bc2daa7e702b8a47519815bf976316f0e5c Mon Sep 17 00:00:00 2001
From: "nenka.lab" <mail@zabocho.dev>
Date: Wed, 7 Oct 2026 12:45:22 +0900
Subject: [PATCH 1/2] feat: add the tooling component for editor language
 support

---
 .../xfl/msgbot/plugin/ipc/PluginService.kt    |  11 +
 .../api/discovery/PluginManifestSchema.kt     |   6 +
 .../plugin/api/remote/RemoteLanguageTools.kt  | 166 ++++++++++++++
 .../plugin/api/remote/ToolingEndpoint.kt      | 196 +++++++++++++++++
 .../msgbot/plugin/api/remote/ToolingWire.kt   | 145 +++++++++++++
 .../com/xfl/msgbot/plugin/api/remote/Wire.kt  |  16 +-
 .../plugin/api/tooling/LanguageTools.kt       | 168 +++++++++++++++
 .../plugin/api/remote/ToolingSessionTest.kt   | 203 ++++++++++++++++++
 readme.md                                     |  33 ++-
 .../msgbot/plugin/tck/ToolingConformance.kt   | 103 +++++++++
 .../xfl/msgbot/plugin/tck/ToolingHarness.kt   |  55 +++++
 .../tck/ExampleToolingConformanceTest.kt      |  43 ++++
 12 files changed, 1143 insertions(+), 2 deletions(-)
 create mode 100644 contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
 create mode 100644 contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingEndpoint.kt
 create mode 100644 contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingWire.kt
 create mode 100644 contract/src/main/kotlin/com/xfl/msgbot/plugin/api/tooling/LanguageTools.kt
 create mode 100644 contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
 create mode 100644 tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingConformance.kt
 create mode 100644 tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingHarness.kt
 create mode 100644 tck/src/test/kotlin/com/xfl/msgbot/plugin/tck/ExampleToolingConformanceTest.kt

diff --git a/android/src/main/java/com/xfl/msgbot/plugin/ipc/PluginService.kt b/android/src/main/java/com/xfl/msgbot/plugin/ipc/PluginService.kt
index 0c09f95..e7430df 100644
--- a/android/src/main/java/com/xfl/msgbot/plugin/ipc/PluginService.kt
+++ b/android/src/main/java/com/xfl/msgbot/plugin/ipc/PluginService.kt
@@ -19,6 +19,8 @@ import com.xfl.msgbot.plugin.api.engine.ScriptEngineFactory
 import com.xfl.msgbot.plugin.api.provider.Provider
 import com.xfl.msgbot.plugin.api.remote.EngineEndpoint
 import com.xfl.msgbot.plugin.api.remote.ProviderEndpoint
+import com.xfl.msgbot.plugin.api.remote.ToolingEndpoint
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.CopyOnWriteArrayList
 import java.util.concurrent.RejectedExecutionException
@@ -34,6 +36,7 @@ import java.util.concurrent.atomic.AtomicLong
  * class MyPluginService : PluginService() {
  *     override val engines = mapOf("luaj" to ScriptEngineFactory(::LuaEngine))
  *     override val providers = mapOf("weather" to ::WeatherProvider)
+ *     override val tooling = mapOf("ts-tools" to ToolingFactory(::TypeScriptTools))
  * }
  * ```
  *
@@ -43,6 +46,7 @@ import java.util.concurrent.atomic.AtomicLong
 open class PluginService : Service() {
     protected open val engines: Map<String, ScriptEngineFactory> = emptyMap()
     protected open val providers: Map<String, () -> Provider> = emptyMap()
+    protected open val tooling: Map<String, ToolingFactory> = emptyMap()
 
     private class Session(
         val callback: IPluginCallback,
@@ -87,6 +91,12 @@ open class PluginService : Service() {
                                     onProtocolError = lost,
                                     factory = providers[component] ?: throw IllegalArgumentException("This plugin has no provider '$component'"),
                                 )
+                            PluginRole.TOOLING ->
+                                ToolingEndpoint(
+                                    transport,
+                                    tooling[component] ?: throw IllegalArgumentException("This plugin has no tooling '$component'"),
+                                    onProtocolError = lost,
+                                )
                             else -> throw IllegalArgumentException("Unknown role '$role'")
                         }
                     } catch (e: Throwable) {
@@ -184,6 +194,7 @@ open class PluginService : Service() {
         when (endpoint) {
             is EngineEndpoint -> endpoint.isStopped
             is ProviderEndpoint -> endpoint.isStopped
+            is ToolingEndpoint -> endpoint.isStopped
             else -> true
         }
 
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/discovery/PluginManifestSchema.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/discovery/PluginManifestSchema.kt
index f66ae95..00a7a12 100644
--- a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/discovery/PluginManifestSchema.kt
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/discovery/PluginManifestSchema.kt
@@ -22,6 +22,7 @@ object PluginManifestSchema {
     const val TAG_LANGUAGE = "language"
     const val TAG_PROFILE = "profile"
     const val TAG_PROVIDER = "provider"
+    const val TAG_TOOLING = "tooling"
     const val TAG_OPTION = "option"
 
     /** Root attribute: the plugin's [com.xfl.msgbot.plugin.api.protocol.ProtocolVersion.CURRENT]. */
@@ -58,6 +59,10 @@ object PluginManifestSchema {
     /** Space-separated namespaces. Publishing an unlisted namespace is refused. */
     const val ATTR_PROVIDES = "provides"
 
+    // <tooling>
+    /** Space-separated language names (`<language name>`) the tooling serves, such as `javascript typescript`. */
+    const val ATTR_LANGUAGES = "languages"
+
     // <option>
     const val ATTR_KEY = "key"
     const val ATTR_TYPE = "type"
@@ -70,4 +75,5 @@ object PluginManifestSchema {
 object PluginRole {
     const val ENGINE = "engine"
     const val PROVIDER = "provider"
+    const val TOOLING = "tooling"
 }
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
new file mode 100644
index 0000000..6dfc343
--- /dev/null
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
@@ -0,0 +1,166 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.api.remote
+
+import com.xfl.msgbot.plugin.api.call.CallResult
+import com.xfl.msgbot.plugin.api.remote.Wire.map
+import com.xfl.msgbot.plugin.api.remote.Wire.string
+import com.xfl.msgbot.plugin.api.rpc.PluginTransport
+import com.xfl.msgbot.plugin.api.rpc.RpcHandler
+import com.xfl.msgbot.plugin.api.rpc.RpcPeer
+import com.xfl.msgbot.plugin.api.tooling.LanguageTools
+import com.xfl.msgbot.plugin.api.tooling.ToolCompletion
+import com.xfl.msgbot.plugin.api.tooling.ToolDiagnostic
+import com.xfl.msgbot.plugin.api.tooling.ToolHover
+import com.xfl.msgbot.plugin.api.tooling.ToolSignatureHelp
+import com.xfl.msgbot.plugin.api.tooling.ToolingCapability
+import com.xfl.msgbot.plugin.api.tooling.ToolingChange
+import com.xfl.msgbot.plugin.api.tooling.ToolingHost
+import com.xfl.msgbot.plugin.api.tooling.ToolingWorkspace
+import com.xfl.msgbot.plugin.api.value.Value
+import com.xfl.msgbot.plugin.api.value.asArrayOrNull
+import com.xfl.msgbot.plugin.api.value.asStringOrNull
+import java.util.concurrent.Executor
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.Semaphore
+
+/**
+ * Host-side [LanguageTools] proxy for the tooling in a plugin. A call fails with
+ * [com.xfl.msgbot.plugin.api.call.CallException] when the plugin answers with an error or does not
+ * answer within [timeoutMs]; [diagnostics], [complete], [hover] and [signatureHelp] carry that
+ * deadline, so a plugin that falls behind skips the questions that are already stale.
+ *
+ * The plugin's reads of [files] run on [callExecutor], so a slow disk does not hold the transport.
+ */
+class RemoteLanguageTools private constructor(
+    transport: PluginTransport,
+    private val files: ToolingHost,
+    private val callExecutor: Executor,
+    private val timeoutMs: Long,
+    maxPendingCalls: Int,
+    private val onError: (String) -> Unit,
+) : LanguageTools {
+    private val callSlots = Semaphore(maxPendingCalls.also { require(it > 0) })
+
+    override var capabilities: Set<ToolingCapability> = emptySet()
+        private set
+
+    private val handler =
+        object : RpcHandler {
+            override fun onRequest(
+                method: String,
+                params: Value,
+                reply: (CallResult) -> Unit,
+            ) {
+                if (method != Wire.TOOLING_READ && method != Wire.TOOLING_LIST) {
+                    return reply(CallResult.failed("The host does not answer '$method' from a tooling plugin"))
+                }
+                val map: Map<String, Value>
+                val path: String
+                try {
+                    map = params.map()
+                    path = map.string("path")
+                } catch (e: Exception) {
+                    return reply(CallResult.badArgs("Malformed $method: ${e.message}"))
+                }
+                if (!callSlots.tryAcquire()) return reply(CallResult.unavailable("Too many reads are waiting"))
+                try {
+                    callExecutor.execute {
+                        try {
+                            val result =
+                                when {
+                                    Wire.expired(map) -> CallResult.unavailable("The read waited past the plugin's deadline and was skipped")
+                                    method == Wire.TOOLING_READ -> CallResult.ok(files.read(path)?.let(Value::of) ?: Value.VNull)
+                                    else -> CallResult.ok(files.list(path)?.let { names -> Value.VArray(names.map(Value::of)) } ?: Value.VNull)
+                                }
+                            reply(result)
+                        } catch (e: Throwable) {
+                            reply(Wire.errorOf(e))
+                        } finally {
+                            callSlots.release()
+                        }
+                    }
+                } catch (_: RejectedExecutionException) {
+                    callSlots.release()
+                    reply(CallResult.unavailable("The host is shutting down"))
+                }
+            }
+
+            override fun onNotify(
+                method: String,
+                params: Value,
+            ) {
+                if (method == Wire.TOOLING_ERROR) {
+                    onError(params.map()["message"]?.asStringOrNull() ?: "The tooling reported an error")
+                }
+            }
+        }
+
+    private val peer = RpcPeer(transport, handler, onError)
+
+    override fun configure(workspace: ToolingWorkspace) {
+        peer.request(Wire.TOOLING_CONFIGURE, ToolingWire.workspace(workspace), timeoutMs).getOrThrow()
+    }
+
+    override fun sync(change: ToolingChange) {
+        peer.request(Wire.TOOLING_SYNC, ToolingWire.change(change), timeoutMs).getOrThrow()
+    }
+
+    override fun diagnostics(path: String): List<ToolDiagnostic> =
+        ToolingWire.diagnosticsOf(ask(Wire.TOOLING_DIAGNOSTICS, path))
+
+    override fun complete(
+        path: String,
+        offset: Int,
+    ): List<ToolCompletion> = ToolingWire.completionsOf(ask(Wire.TOOLING_COMPLETE, path, offset))
+
+    override fun hover(
+        path: String,
+        offset: Int,
+    ): ToolHover? = ToolingWire.hoverOf(ask(Wire.TOOLING_HOVER, path, offset))
+
+    override fun signatureHelp(
+        path: String,
+        offset: Int,
+    ): ToolSignatureHelp? = ToolingWire.signatureHelpOf(ask(Wire.TOOLING_SIGNATURE, path, offset))
+
+    private fun ask(
+        method: String,
+        path: String,
+        offset: Int? = null,
+    ): Value =
+        peer
+            .request(method, Wire.obj("path" to path, "offset" to offset, Wire.deadline(timeoutMs)), timeoutMs)
+            .getOrThrow()
+
+    override fun close() {
+        peer.notify(Wire.CLOSE)
+        peer.close()
+    }
+
+    companion object {
+        /** Performs the `hello` handshake. On failure closes the transport and throws. */
+        fun connect(
+            transport: PluginTransport,
+            files: ToolingHost,
+            callExecutor: Executor,
+            timeoutMs: Long = 10_000,
+            maxPendingCalls: Int = 32,
+            onError: (String) -> Unit = {},
+        ): RemoteLanguageTools {
+            val tools = RemoteLanguageTools(transport, files, callExecutor, timeoutMs, maxPendingCalls, onError)
+            try {
+                val hello = Wire.checkHello(tools.peer.request(Wire.HELLO, Wire.hello(), Wire.HELLO_TIMEOUT_MS))
+                tools.capabilities =
+                    hello["capabilities"]?.asArrayOrNull()?.mapNotNull { it.asStringOrNull()?.let(ToolingCapability::of) }?.toSet().orEmpty()
+            } catch (e: Exception) {
+                tools.peer.close()
+                throw e
+            }
+            return tools
+        }
+    }
+}
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingEndpoint.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingEndpoint.kt
new file mode 100644
index 0000000..b1779e2
--- /dev/null
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingEndpoint.kt
@@ -0,0 +1,196 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.api.remote
+
+import com.xfl.msgbot.plugin.api.call.CallException
+import com.xfl.msgbot.plugin.api.call.CallResult
+import com.xfl.msgbot.plugin.api.engine.EngineThread
+import com.xfl.msgbot.plugin.api.remote.Wire.map
+import com.xfl.msgbot.plugin.api.remote.Wire.string
+import com.xfl.msgbot.plugin.api.rpc.PluginTransport
+import com.xfl.msgbot.plugin.api.rpc.RpcHandler
+import com.xfl.msgbot.plugin.api.rpc.RpcPeer
+import com.xfl.msgbot.plugin.api.tooling.LanguageTools
+import com.xfl.msgbot.plugin.api.tooling.ToolingContext
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
+import com.xfl.msgbot.plugin.api.tooling.ToolingHost
+import com.xfl.msgbot.plugin.api.value.Value
+import com.xfl.msgbot.plugin.api.value.asArrayOrNull
+import com.xfl.msgbot.plugin.api.value.asIntOrNull
+import com.xfl.msgbot.plugin.api.value.asStringOrNull
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * Plugin side of a tooling session: creates the [LanguageTools] and runs every call on one thread.
+ * Created per session by [com.xfl.msgbot.plugin.ipc.PluginService].
+ *
+ * A question that is picked up after the host stopped waiting for it is skipped, so typing fast
+ * does not queue up a stale analysis behind each keystroke. [configure][LanguageTools.configure]
+ * and [sync][LanguageTools.sync] are never skipped.
+ */
+class ToolingEndpoint(
+    transport: PluginTransport,
+    private val factory: ToolingFactory,
+    private val callTimeoutMs: Long = 10_000,
+    private val onProtocolError: (String) -> Unit = {},
+) : AutoCloseable {
+    private val closed = AtomicBoolean(false)
+    private val thread: EngineThread = EngineThread("plugin-tooling") { message, _ -> reportError(message) }
+
+    @Volatile private var tools: LanguageTools? = null
+
+    @Volatile private var startupFailure: String? = null
+
+    private val context: ToolingContext =
+        object : ToolingContext {
+            override val host: ToolingHost =
+                object : ToolingHost {
+                    override fun read(path: String): String? = ask(Wire.TOOLING_READ, path)?.asStringOrNull()
+
+                    override fun list(path: String): List<String>? = ask(Wire.TOOLING_LIST, path)?.asArrayOrNull()?.mapNotNull { it.asStringOrNull() }
+
+                    private fun ask(
+                        method: String,
+                        path: String,
+                    ): Value? {
+                        val params = Wire.obj("path" to path, Wire.deadline(callTimeoutMs))
+                        return (peer.request(method, params, callTimeoutMs) as? CallResult.Ok)?.value?.takeIf { it !is Value.VNull }
+                    }
+                }
+
+            override fun reportError(
+                message: String,
+                error: Throwable?,
+            ) = this@ToolingEndpoint.reportError(message)
+        }
+
+    private val handler: RpcHandler =
+        object : RpcHandler {
+            override fun onRequest(
+                method: String,
+                params: Value,
+                reply: (CallResult) -> Unit,
+            ) {
+                val map: Map<String, Value>
+                try {
+                    map = if (method == Wire.HELLO) emptyMap() else params.map()
+                } catch (e: Exception) {
+                    return reply(CallResult.badArgs("Malformed $method: ${e.message}"))
+                }
+                when (method) {
+                    Wire.HELLO -> onTools(reply) { tools -> Wire.answerHello(params, extra = { capabilities(tools) }).getOrThrow() }
+                    Wire.TOOLING_CONFIGURE ->
+                        onTools(reply) { tools ->
+                            tools.configure(ToolingWire.workspaceOf(params))
+                            Value.VNull
+                        }
+                    Wire.TOOLING_SYNC ->
+                        onTools(reply) { tools ->
+                            tools.sync(ToolingWire.changeOf(params))
+                            Value.VNull
+                        }
+                    Wire.TOOLING_DIAGNOSTICS ->
+                        query(map, reply) { tools, path -> ToolingWire.diagnostics(tools.diagnostics(path)) }
+                    Wire.TOOLING_COMPLETE ->
+                        query(map, reply) { tools, path -> ToolingWire.completions(tools.complete(path, offset(map))) }
+                    Wire.TOOLING_HOVER -> query(map, reply) { tools, path -> ToolingWire.hover(tools.hover(path, offset(map))) }
+                    Wire.TOOLING_SIGNATURE ->
+                        query(map, reply) { tools, path -> ToolingWire.signatureHelp(tools.signatureHelp(path, offset(map))) }
+                    else -> reply(CallResult.failed("A tooling plugin does not answer '$method'"))
+                }
+            }
+
+            override fun onNotify(
+                method: String,
+                params: Value,
+            ) {
+                if (method == Wire.CLOSE) close()
+            }
+        }
+
+    private val constructed = CountDownLatch(1)
+
+    init {
+        thread.execute {
+            constructed.await()
+            try {
+                tools = factory.create(context)
+            } catch (e: Throwable) {
+                startupFailure = "The tooling could not start: ${e.message ?: e.javaClass.simpleName}"
+                reportError(startupFailure!!)
+            }
+        }
+    }
+
+    private val peer: RpcPeer = RpcPeer(transport, handler, onProtocolError)
+
+    init {
+        constructed.countDown()
+    }
+
+    /** Closed, and the tooling's thread has stopped. */
+    val isStopped: Boolean get() = closed.get() && thread.isTerminated
+
+    private fun capabilities(tools: LanguageTools): Map<String, Any?> = mapOf("capabilities" to tools.capabilities.map { it.wire })
+
+    private fun offset(map: Map<String, Value>): Int = map["offset"]?.asIntOrNull() ?: throw CallException.badArgs("'offset' is missing")
+
+    private fun query(
+        map: Map<String, Value>,
+        reply: (CallResult) -> Unit,
+        block: (LanguageTools, String) -> Value,
+    ) {
+        val path =
+            try {
+                map.string("path")
+            } catch (e: Exception) {
+                return reply(CallResult.badArgs("Malformed query: ${e.message}"))
+            }
+        onTools(reply) { tools ->
+            if (Wire.expired(map)) throw CallException.unavailable("The question waited past the host's deadline and was skipped")
+            block(tools, path)
+        }
+    }
+
+    private fun reportError(message: String) = peer.notify(Wire.TOOLING_ERROR, Wire.obj("message" to message))
+
+    /** Catches Throwable so every request gets a reply. */
+    private fun onTools(
+        reply: (CallResult) -> Unit,
+        block: (LanguageTools) -> Value,
+    ) {
+        try {
+            thread.execute {
+                val result =
+                    if (closed.get()) {
+                        CallResult.unavailable("The tooling session is closed")
+                    } else {
+                        try {
+                            val tools = tools ?: throw IllegalStateException(startupFailure ?: "The tooling is not running")
+                            CallResult.ok(block(tools))
+                        } catch (e: Throwable) {
+                            Wire.errorOf(e)
+                        }
+                    }
+                reply(result)
+            }
+        } catch (_: RejectedExecutionException) {
+            reply(CallResult.unavailable("The tooling session is closed"))
+        }
+    }
+
+    override fun close() {
+        if (!closed.compareAndSet(false, true)) return
+        peer.close()
+        try {
+            thread.execute { runCatching { tools?.close() } }
+        } catch (_: RejectedExecutionException) {
+        }
+        thread.shutdown()
+    }
+}
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingWire.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingWire.kt
new file mode 100644
index 0000000..97c0daa
--- /dev/null
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingWire.kt
@@ -0,0 +1,145 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.api.remote
+
+import com.xfl.msgbot.plugin.api.remote.Wire.list
+import com.xfl.msgbot.plugin.api.remote.Wire.map
+import com.xfl.msgbot.plugin.api.remote.Wire.string
+import com.xfl.msgbot.plugin.api.tooling.ToolCompletion
+import com.xfl.msgbot.plugin.api.tooling.ToolDiagnostic
+import com.xfl.msgbot.plugin.api.tooling.ToolHover
+import com.xfl.msgbot.plugin.api.tooling.ToolSeverity
+import com.xfl.msgbot.plugin.api.tooling.ToolSignature
+import com.xfl.msgbot.plugin.api.tooling.ToolSignatureHelp
+import com.xfl.msgbot.plugin.api.tooling.ToolingChange
+import com.xfl.msgbot.plugin.api.tooling.ToolingFile
+import com.xfl.msgbot.plugin.api.tooling.ToolingWorkspace
+import com.xfl.msgbot.plugin.api.value.Value
+import com.xfl.msgbot.plugin.api.value.asIntOrNull
+import com.xfl.msgbot.plugin.api.value.asStringOrNull
+
+/**
+ * Encoding of the tooling role's requests and answers. What the host reads from a plugin is read
+ * leniently: an entry it cannot read is left out, so one bad completion does not hide the rest.
+ */
+internal object ToolingWire {
+    fun workspace(workspace: ToolingWorkspace): Value =
+        Wire.obj("language" to workspace.language, "options" to workspace.options, "libs" to workspace.libs.map(::file))
+
+    fun workspaceOf(value: Value): ToolingWorkspace {
+        val map = value.map()
+        return ToolingWorkspace(
+            language = map.string("language"),
+            options = map["options"]?.map()?.mapValues { (_, v) -> v.asStringOrNull().orEmpty() }.orEmpty(),
+            libs = map["libs"]?.list()?.map(::fileOf).orEmpty(),
+        )
+    }
+
+    fun change(change: ToolingChange): Value = Wire.obj("upserts" to change.upserts.map(::file), "removes" to change.removes)
+
+    fun changeOf(value: Value): ToolingChange {
+        val map = value.map()
+        return ToolingChange(
+            upserts = map["upserts"]?.list()?.map(::fileOf).orEmpty(),
+            removes = map["removes"]?.list()?.map { it.asStringOrNull() ?: throw IllegalArgumentException("A path is text") }.orEmpty(),
+        )
+    }
+
+    fun diagnostics(items: List<ToolDiagnostic>): Value =
+        Value.VArray(
+            items.map {
+                Wire.obj("start" to it.start, "end" to it.end, "severity" to it.severity.wire, "message" to it.message, "code" to it.code)
+            },
+        )
+
+    fun diagnosticsOf(value: Value): List<ToolDiagnostic> =
+        lenient(value) { map ->
+            ToolDiagnostic(
+                start = map.int("start"),
+                end = map.int("end"),
+                severity = ToolSeverity.of(map["severity"]?.asStringOrNull()),
+                message = map.string("message"),
+                code = map["code"]?.asStringOrNull(),
+            )
+        }
+
+    fun completions(items: List<ToolCompletion>): Value =
+        Value.VArray(
+            items.map {
+                Wire.obj(
+                    "label" to it.label,
+                    "kind" to it.kind,
+                    "detail" to it.detail,
+                    "doc" to it.doc,
+                    "insert" to it.insert,
+                    "replaceStart" to it.replaceStart,
+                    "replaceEnd" to it.replaceEnd,
+                )
+            },
+        )
+
+    fun completionsOf(value: Value): List<ToolCompletion> =
+        lenient(value) { map ->
+            ToolCompletion(
+                label = map.string("label"),
+                kind = map["kind"]?.asStringOrNull().orEmpty(),
+                detail = map["detail"]?.asStringOrNull(),
+                doc = map["doc"]?.asStringOrNull(),
+                insert = map["insert"]?.asStringOrNull(),
+                replaceStart = map["replaceStart"]?.asIntOrNull(),
+                replaceEnd = map["replaceEnd"]?.asIntOrNull(),
+            )
+        }
+
+    fun hover(hover: ToolHover?): Value =
+        if (hover == null) Value.VNull else Wire.obj("start" to hover.start, "end" to hover.end, "text" to hover.text)
+
+    fun hoverOf(value: Value): ToolHover? =
+        runCatching {
+            val map = value.map()
+            ToolHover(map.int("start"), map.int("end"), map.string("text"))
+        }.getOrNull()
+
+    fun signatureHelp(help: ToolSignatureHelp?): Value =
+        if (help == null) {
+            Value.VNull
+        } else {
+            Wire.obj(
+                "signatures" to
+                    help.signatures.map { Wire.obj("label" to it.label, "doc" to it.doc, "parameters" to it.parameters) },
+                "activeSignature" to help.activeSignature,
+                "activeParameter" to help.activeParameter,
+            )
+        }
+
+    fun signatureHelpOf(value: Value): ToolSignatureHelp? =
+        runCatching {
+            val map = value.map()
+            val signatures =
+                lenient(map.getValue("signatures")) { signature ->
+                    ToolSignature(
+                        label = signature.string("label"),
+                        doc = signature["doc"]?.asStringOrNull(),
+                        parameters = signature["parameters"]?.list()?.mapNotNull { it.asStringOrNull() }.orEmpty(),
+                    )
+                }
+            ToolSignatureHelp(signatures, map["activeSignature"]?.asIntOrNull() ?: 0, map["activeParameter"]?.asIntOrNull() ?: 0)
+        }.getOrNull()?.takeIf { it.signatures.isNotEmpty() }
+
+    private fun file(file: ToolingFile): Value = Wire.obj("path" to file.path, "text" to file.text)
+
+    private fun fileOf(value: Value): ToolingFile {
+        val map = value.map()
+        return ToolingFile(map.string("path"), map.string("text"))
+    }
+
+    private fun <T> lenient(
+        value: Value,
+        read: (Map<String, Value>) -> T,
+    ): List<T> = (value as? Value.VArray)?.items.orEmpty().mapNotNull { runCatching { read(it.map()) }.getOrNull() }
+
+    private fun Map<String, Value>.int(key: String): Int = this[key]?.asIntOrNull() ?: throw IllegalArgumentException("'$key' is missing")
+}
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/Wire.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/Wire.kt
index 6e26da5..65260bf 100644
--- a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/Wire.kt
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/Wire.kt
@@ -48,6 +48,19 @@ internal object Wire {
     const val PROVIDER_EMIT = "provider.emit"
     const val PROVIDER_ERROR = "provider.error"
 
+    // Tooling role: host -> plugin.
+    const val TOOLING_CONFIGURE = "tooling.configure"
+    const val TOOLING_SYNC = "tooling.sync"
+    const val TOOLING_DIAGNOSTICS = "tooling.diagnostics"
+    const val TOOLING_COMPLETE = "tooling.complete"
+    const val TOOLING_HOVER = "tooling.hover"
+    const val TOOLING_SIGNATURE = "tooling.signature"
+
+    // Tooling role: plugin -> host.
+    const val TOOLING_READ = "tooling.read"
+    const val TOOLING_LIST = "tooling.list"
+    const val TOOLING_ERROR = "tooling.error"
+
     const val HELLO_TIMEOUT_MS = 10_000L
 
     /**
@@ -72,6 +85,7 @@ internal object Wire {
     /** Plugin's reply to [hello]: agreed protocol and, for a provider, its [modules]. Unavailable if ranges do not overlap. */
     fun answerHello(
         params: Value,
+        extra: () -> Map<String, Any?> = { emptyMap() },
         modules: () -> List<ModuleSpec> = { emptyList() },
     ): CallResult {
         val offer = params.asObjectOrNull().orEmpty()
@@ -83,7 +97,7 @@ internal object Wire {
                     "This plugin speaks protocol ${ProtocolVersion.MIN_SUPPORTED}..${ProtocolVersion.CURRENT}; " +
                         "the host speaks $hostMin..$hostMax",
                 )
-        return CallResult.ok(obj("protocol" to agreed, "modules" to modules().map { it.toValue() }))
+        return CallResult.ok(obj("protocol" to agreed, "modules" to modules().map { it.toValue() }, *extra().toList().toTypedArray()))
     }
 
     /** Validates the plugin's [hello] reply. */
diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/tooling/LanguageTools.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/tooling/LanguageTools.kt
new file mode 100644
index 0000000..0df7a7f
--- /dev/null
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/tooling/LanguageTools.kt
@@ -0,0 +1,168 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.api.tooling
+
+/**
+ * What a plugin gives the editor for one language: diagnostics, completion, hover and signature
+ * help. The host sends the text being edited and asks questions about it; it never runs the
+ * language server's code, and the plugin never edits files.
+ *
+ * Calls arrive one at a time on one thread, in the order the host made them. Everything is plain
+ * text, so an implementation may be a language server, a type checker library or a hand-written
+ * parser. Offsets are UTF-16 code units from the start of the file, the unit of Java and
+ * JavaScript strings and of the editor's own indexes.
+ *
+ * Every function but [configure] and [sync] has an empty default so a tool implements only what
+ * it can answer. It lists those in [capabilities]; the host does not ask for the others.
+ */
+interface LanguageTools : AutoCloseable {
+    val capabilities: Set<ToolingCapability>
+
+    /**
+     * Starts or restarts the workspace. Drops every file from earlier calls, so [sync] sends the
+     * documents again.
+     */
+    fun configure(workspace: ToolingWorkspace)
+
+    /** Applies edits to the host's view of the files. [ToolingChange.removes] is applied first. */
+    fun sync(change: ToolingChange)
+
+    fun diagnostics(path: String): List<ToolDiagnostic> = emptyList()
+
+    fun complete(
+        path: String,
+        offset: Int,
+    ): List<ToolCompletion> = emptyList()
+
+    fun hover(
+        path: String,
+        offset: Int,
+    ): ToolHover? = null
+
+    fun signatureHelp(
+        path: String,
+        offset: Int,
+    ): ToolSignatureHelp? = null
+
+    override fun close() = Unit
+}
+
+enum class ToolingCapability(val wire: String) {
+    DIAGNOSTICS("diagnostics"),
+    COMPLETION("completion"),
+    HOVER("hover"),
+    SIGNATURE_HELP("signatureHelp"),
+    ;
+
+    companion object {
+        /** Unknown names, from a newer plugin, are left out. */
+        fun of(wire: String): ToolingCapability? = entries.firstOrNull { it.wire == wire }
+    }
+}
+
+/** Creates the tools of one session. [create] runs on the thread that then serves every call. */
+fun interface ToolingFactory {
+    fun create(context: ToolingContext): LanguageTools
+}
+
+interface ToolingContext {
+    /** Reads what the host allows: the project's files and the declaration files it ships. */
+    val host: ToolingHost
+
+    /** Tells the host about a failure no request is waiting on. */
+    fun reportError(
+        message: String,
+        error: Throwable? = null,
+    )
+}
+
+/**
+ * Read-only access to the host's files, for a tool that follows imports. Calls block until the
+ * host answers, so make them from the tool's own thread, and cache what you read.
+ */
+interface ToolingHost {
+    /** The text of the file at [path], or null if it does not exist, is not text or is not readable by the plugin. */
+    fun read(path: String): String?
+
+    /** The names inside the directory at [path], with `/` after a directory's, or null if there is no such directory. */
+    fun list(path: String): List<String>?
+}
+
+/**
+ * [libs] are declaration files that belong to no project, such as the standard library or the
+ * API a project can call. [options] are the plugin's own settings.
+ */
+class ToolingWorkspace(
+    val language: String,
+    val options: Map<String, String> = emptyMap(),
+    val libs: List<ToolingFile> = emptyList(),
+)
+
+/** [path] is the host's path; the same string names the file in later calls and in [ToolingHost]. */
+class ToolingFile(
+    val path: String,
+    val text: String,
+)
+
+class ToolingChange(
+    val upserts: List<ToolingFile> = emptyList(),
+    val removes: List<String> = emptyList(),
+)
+
+enum class ToolSeverity(val wire: String) {
+    ERROR("error"),
+    WARNING("warning"),
+    INFO("info"),
+    HINT("hint"),
+    ;
+
+    companion object {
+        fun of(wire: String?): ToolSeverity = entries.firstOrNull { it.wire == wire } ?: ERROR
+    }
+}
+
+/** A problem in `[start, end)`. [code] is the tool's own identifier for the kind of problem. */
+data class ToolDiagnostic(
+    val start: Int,
+    val end: Int,
+    val severity: ToolSeverity,
+    val message: String,
+    val code: String? = null,
+)
+
+/**
+ * A completion. The host replaces `[replaceStart, replaceEnd)` with [insert], or with [label]
+ * and the word before the cursor when [insert] is null. [kind] is a free word such as `function`,
+ * `property` or `keyword`; the host shows an icon for those it knows.
+ */
+data class ToolCompletion(
+    val label: String,
+    val kind: String = "",
+    val detail: String? = null,
+    val doc: String? = null,
+    val insert: String? = null,
+    val replaceStart: Int? = null,
+    val replaceEnd: Int? = null,
+)
+
+/** [text] is plain text; the host does not render markup. */
+data class ToolHover(
+    val start: Int,
+    val end: Int,
+    val text: String,
+)
+
+data class ToolSignature(
+    val label: String,
+    val doc: String? = null,
+    val parameters: List<String> = emptyList(),
+)
+
+data class ToolSignatureHelp(
+    val signatures: List<ToolSignature>,
+    val activeSignature: Int = 0,
+    val activeParameter: Int = 0,
+)
diff --git a/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt b/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
new file mode 100644
index 0000000..77b444e
--- /dev/null
+++ b/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
@@ -0,0 +1,203 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.api.remote
+
+import com.xfl.msgbot.plugin.api.call.CallException
+import com.xfl.msgbot.plugin.api.call.ErrorCode
+import com.xfl.msgbot.plugin.api.rpc.LoopbackTransport
+import com.xfl.msgbot.plugin.api.tooling.LanguageTools
+import com.xfl.msgbot.plugin.api.tooling.ToolCompletion
+import com.xfl.msgbot.plugin.api.tooling.ToolDiagnostic
+import com.xfl.msgbot.plugin.api.tooling.ToolHover
+import com.xfl.msgbot.plugin.api.tooling.ToolSeverity
+import com.xfl.msgbot.plugin.api.tooling.ToolSignature
+import com.xfl.msgbot.plugin.api.tooling.ToolSignatureHelp
+import com.xfl.msgbot.plugin.api.tooling.ToolingCapability
+import com.xfl.msgbot.plugin.api.tooling.ToolingChange
+import com.xfl.msgbot.plugin.api.tooling.ToolingContext
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
+import com.xfl.msgbot.plugin.api.tooling.ToolingFile
+import com.xfl.msgbot.plugin.api.tooling.ToolingHost
+import com.xfl.msgbot.plugin.api.tooling.ToolingWorkspace
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import kotlin.test.AfterTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+
+class ToolingSessionTest {
+    private class Tools(val context: ToolingContext) : LanguageTools {
+        override val capabilities = setOf(ToolingCapability.DIAGNOSTICS, ToolingCapability.COMPLETION, ToolingCapability.HOVER)
+        var workspace: ToolingWorkspace? = null
+        val texts = linkedMapOf<String, String>()
+        val threads = CopyOnWriteArrayList<Thread>()
+        val holding = CountDownLatch(1)
+        val release = CountDownLatch(1)
+        val diagnosed = CopyOnWriteArrayList<String>()
+
+        override fun configure(workspace: ToolingWorkspace) {
+            threads += Thread.currentThread()
+            this.workspace = workspace
+            texts.clear()
+            workspace.libs.forEach { texts[it.path] = it.text }
+        }
+
+        override fun sync(change: ToolingChange) {
+            threads += Thread.currentThread()
+            change.removes.forEach { texts.remove(it) }
+            change.upserts.forEach { texts[it.path] = it.text }
+        }
+
+        override fun diagnostics(path: String): List<ToolDiagnostic> {
+            threads += Thread.currentThread()
+            diagnosed += path
+            if (path == "/slow.js") {
+                holding.countDown()
+                release.await(5, TimeUnit.SECONDS)
+            }
+            if (path == "/broken.js") throw CallException.unavailable("checker crashed")
+            val text = texts[path] ?: return emptyList()
+            val at = text.indexOf("oops")
+            return if (at < 0) emptyList() else listOf(ToolDiagnostic(at, at + 4, ToolSeverity.WARNING, "no oops", "oops"))
+        }
+
+        override fun complete(
+            path: String,
+            offset: Int,
+        ): List<ToolCompletion> {
+            val imported = context.host.read("/project/dep.d.ts")
+            val names = context.host.list("/project")
+            return listOf(
+                ToolCompletion("reply", "function", "(text: string)", insert = "reply", replaceStart = offset - 2, replaceEnd = offset),
+                ToolCompletion("dep", "variable", detail = imported, doc = names?.joinToString()),
+            )
+        }
+
+        override fun hover(
+            path: String,
+            offset: Int,
+        ) = if (offset == 3) ToolHover(0, 5, "const bot: Bot") else null
+    }
+
+    private val transports = LoopbackTransport.pair()
+    private val files = linkedMapOf("/project/dep.d.ts" to "declare const dep: number")
+    private val errors = CopyOnWriteArrayList<String>()
+    private lateinit var tools: Tools
+    private val endpoint = ToolingEndpoint(transports.second, ToolingFactory { Tools(it).also { created -> tools = created } })
+    private val callExecutor = Executors.newCachedThreadPool { r -> Thread(r, "tooling-host-reads").apply { isDaemon = true } }
+    private val host =
+        object : ToolingHost {
+            override fun read(path: String): String? = files[path]
+
+            override fun list(path: String): List<String>? = if (path == "/project") listOf("dep.d.ts", "src/") else null
+        }
+    private val remote = RemoteLanguageTools.connect(transports.first, host, callExecutor, timeoutMs = 2_000, onError = { errors += it })
+
+    @AfterTest
+    fun tearDown() {
+        remote.close()
+        endpoint.close()
+        callExecutor.shutdownNow()
+    }
+
+    @Test
+    fun `the host learns what the tooling can answer from hello`() {
+        assertEquals(setOf(ToolingCapability.DIAGNOSTICS, ToolingCapability.COMPLETION, ToolingCapability.HOVER), remote.capabilities)
+    }
+
+    @Test
+    fun `a workspace and its changes reach the tooling`() {
+        remote.configure(ToolingWorkspace("javascript", mapOf("target" to "es5"), listOf(ToolingFile("/lib/api.d.ts", "declare const Api: any"))))
+        remote.sync(ToolingChange(upserts = listOf(ToolingFile("/project/main.js", "bot.oops()"))))
+
+        val workspace = tools.workspace!!
+        assertEquals("javascript", workspace.language)
+        assertEquals(mapOf("target" to "es5"), workspace.options)
+        assertEquals(setOf("/lib/api.d.ts", "/project/main.js"), tools.texts.keys)
+
+        remote.sync(ToolingChange(removes = listOf("/project/main.js")))
+        assertEquals(setOf("/lib/api.d.ts"), tools.texts.keys)
+    }
+
+    @Test
+    fun `diagnostics carry offsets, severity and code`() {
+        remote.sync(ToolingChange(upserts = listOf(ToolingFile("/project/main.js", "bot.oops()"))))
+        assertEquals(
+            listOf(ToolDiagnostic(4, 8, ToolSeverity.WARNING, "no oops", "oops")),
+            remote.diagnostics("/project/main.js"),
+        )
+        assertEquals(emptyList(), remote.diagnostics("/project/other.js"))
+    }
+
+    @Test
+    fun `completions are read with the host files the tool asked for`() {
+        val items = remote.complete("/project/main.js", 10)
+
+        assertEquals(ToolCompletion("reply", "function", "(text: string)", insert = "reply", replaceStart = 8, replaceEnd = 10), items[0])
+        assertEquals("declare const dep: number", items[1].detail)
+        assertEquals("dep.d.ts, src/", items[1].doc)
+    }
+
+    @Test
+    fun `a file the host does not have reads as missing`() {
+        files.clear()
+        val items = remote.complete("/project/main.js", 10)
+        assertNull(items[1].detail)
+    }
+
+    @Test
+    fun `hover is optional`() {
+        assertEquals(ToolHover(0, 5, "const bot: Bot"), remote.hover("/project/main.js", 3))
+        assertNull(remote.hover("/project/main.js", 4))
+        assertNull(remote.signatureHelp("/project/main.js", 3))
+    }
+
+    @Test
+    fun `every call runs on one thread`() {
+        remote.configure(ToolingWorkspace("javascript"))
+        remote.sync(ToolingChange(upserts = listOf(ToolingFile("/a.js", "x"))))
+        remote.diagnostics("/a.js")
+        assertEquals(1, tools.threads.distinct().size)
+    }
+
+    @Test
+    fun `a failure keeps its code across the boundary`() {
+        val e = assertFailsWith<CallException> { remote.diagnostics("/broken.js") }
+        assertEquals(ErrorCode.UNAVAILABLE, e.code)
+        assertEquals("checker crashed", e.message)
+        assertEquals(emptyList(), remote.diagnostics("/project/main.js"), "the session survives a failed question")
+    }
+
+    @Test
+    fun `a question the host gave up on is skipped`() {
+        val slow = Executors.newSingleThreadExecutor().submit<Any?> { runCatching { remote.diagnostics("/slow.js") }.exceptionOrNull() }
+        assertTrue(tools.holding.await(5, TimeUnit.SECONDS))
+        val stale = Executors.newSingleThreadExecutor().submit<Any?> { runCatching { remote.diagnostics("/stale.js") }.exceptionOrNull() }
+        assertTrue(stale.get(5, TimeUnit.SECONDS) is CallException, "the host stops waiting while the tooling is busy")
+        tools.release.countDown()
+        slow.get(5, TimeUnit.SECONDS)
+
+        remote.diagnostics("/project/main.js")
+        assertTrue("/stale.js" !in tools.diagnosed, "picked up after the deadline, it was not run: ${tools.diagnosed}")
+    }
+
+    @Test
+    fun `a tooling that cannot start fails every call with its reason`() {
+        val pair = LoopbackTransport.pair()
+        val broken = ToolingEndpoint(pair.second, ToolingFactory { throw IllegalStateException("no runtime") })
+        try {
+            val e = assertFailsWith<Exception> { RemoteLanguageTools.connect(pair.first, host, callExecutor, timeoutMs = 2_000) }
+            assertTrue(e.message!!.contains("no runtime"), e.message)
+        } finally {
+            broken.close()
+        }
+    }
+}
diff --git a/readme.md b/readme.md
index 9dd4142..ca2846d 100644
--- a/readme.md
+++ b/readme.md
@@ -6,7 +6,7 @@ MessengerBotR의 플러그인 계약이다. 현재 개발 버전은 `0.1.0-SNAPS
 
 | 모듈 | 내용 |
 |---|---|
-| `contract` | 값, API 스키마, 표준 모듈, 엔진·제공자 SPI, 대칭 RPC. Android에 의존하지 않는다. |
+| `contract` | 값, API 스키마, 표준 모듈, 엔진·제공자·도구 SPI, 대칭 RPC. Android에 의존하지 않는다. |
 | `android` | `PluginService`, Binder 세션, 공유 메모리 전송 |
 | `tck` | 엔진과 제공자를 호스트 없이 돌려 보는 `EngineHarness`, `ProviderHarness`. JavaScript 엔진의 적합성 테스트(`JavaScriptEngineConformance`)와 제공자의 적합성 테스트(`ProviderConformance`) |
 
@@ -46,6 +46,37 @@ MessengerBotR의 플러그인 계약이다. 현재 개발 버전은 `0.1.0-SNAPS
 - **세션은 서로 막지 않는다.** 한 플러그인의 세션은 모두 Binder 객체 하나를 쓰지만, 프레임은 세션마다 자기 스레드에서 처리한다. 세션은 연 앱만 쓰고 닫을 수 있다.
 - **멈춘 스레드는 쌓이지 않는다.** 네이티브 코드에서 막힌 스크립트는 interrupt가 닿지 않아, 세션을 닫아도 그 스레드와 메모리가 남는다. `PluginService`는 닫은 세션이 10초 안에 멈추지 않으면 기록하고, 열린 세션이 없거나 그런 세션이 3개가 되면 플러그인 프로세스를 끝낸다. 앱은 플러그인이 죽은 것을 보고 기다리던 요청을 바로 실패시킨 뒤, 아직 쓰는 프로젝트를 다시 연결한다.
 
+## 에디터 도구(Tooling)
+
+엔진, 프로필, 제공자 외에 네 번째 컴포넌트가 하나 더 있다. 에디터가 언어를 이해하도록 돕는 **도구**다. 도구는 스크립트를 실행하지 않는다. 호스트가 편집 중인 텍스트를 보내면 진단(오류와 경고), 자동완성, 호버, 시그니처 도움말로 답한다.
+
+```xml
+<msgbot-plugin protocol="0">
+    <tooling id="ts-tools" label="@string/ts_tools" languages="javascript typescript" />
+</msgbot-plugin>
+```
+
+```kotlin
+class MyPluginService : PluginService() {
+    override val tooling = mapOf("ts-tools" to ToolingFactory(::TypeScriptTools))
+}
+
+class TypeScriptTools(private val context: ToolingContext) : LanguageTools {
+    override val capabilities = setOf(ToolingCapability.DIAGNOSTICS, ToolingCapability.COMPLETION)
+    override fun configure(workspace: ToolingWorkspace) { /* 선언 파일(workspace.libs)로 새로 시작 */ }
+    override fun sync(change: ToolingChange) { /* 바뀐 파일 반영 */ }
+    override fun diagnostics(path: String): List<ToolDiagnostic> = analyze(path)
+    override fun complete(path: String, offset: Int): List<ToolCompletion> = completionsAt(path, offset)
+}
+```
+
+- **서버가 아니다.** 호스트가 요청하고 도구가 답하는 함수 호출이다. JSON-RPC나 별도 프로세스가 없다. 언어 서버를 감싸서 구현해도 되고, 라이브러리를 직접 불러도 된다.
+- **텍스트를 호스트가 보낸다.** `configure`가 작업 공간(언어, 옵션, 프로젝트가 쓰는 API 선언 같은 `libs`)을 정하고, `sync`가 편집한 파일을 알린다. 이어서 `diagnostics`, `complete`, `hover`, `signatureHelp`로 묻는다. 위치는 파일 처음부터 센 UTF-16 코드 단위다.
+- **할 수 있는 것만 구현한다.** 필요한 함수만 재정의하고 `capabilities`에 적는다. 호스트는 적지 않은 것을 묻지 않는다.
+- **파일은 읽기만 한다.** `ToolingContext.host.read`와 `list`로 호스트가 허락한 파일만 읽는다. 가져오는 모듈(`node_modules` 같은 것)을 따라갈 때 쓴다. 호출은 답이 올 때까지 막히므로 도구 스레드에서 부르고 읽은 것은 캐시한다.
+- **도구의 호출은 한 스레드에서 차례로 온다.** 호스트가 기다리기를 그만둔 질문은 차례가 와도 실행하지 않는다. 입력이 빠를 때 오래된 분석이 쌓이지 않게 하기 위해서다. `configure`와 `sync`는 건너뛰지 않는다.
+- **호스트가 같은 계약으로 쓴다.** `RemoteLanguageTools`가 호스트 쪽 프록시이고 `LanguageTools`를 구현한다. 도구가 시작하지 못하거나 질문이 실패하면 호출한 쪽이 `CallException`을 받는다.
+
 ## 플러그인 만들기
 
 APK는 서비스 하나와 매니페스트 XML 하나로 자신이 제공하는 모든 것을 알린다. XML 형식은 `PluginManifestSchema`에 있다. 아래는 누군가 자기 JavaScript API(`api3`)와, DB로 받고 Intent로 보내는 제공자를 함께 내는 플러그인의 예다.
diff --git a/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingConformance.kt b/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingConformance.kt
new file mode 100644
index 0000000..55246b6
--- /dev/null
+++ b/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingConformance.kt
@@ -0,0 +1,103 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.tck
+
+import com.xfl.msgbot.plugin.api.call.CallException
+import com.xfl.msgbot.plugin.api.tooling.ToolingCapability
+import com.xfl.msgbot.plugin.api.tooling.ToolingChange
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
+import com.xfl.msgbot.plugin.api.tooling.ToolingFile
+import com.xfl.msgbot.plugin.api.tooling.ToolingWorkspace
+import org.junit.After
+import org.junit.Before
+import org.junit.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * What every language tooling must do, as tests. Extend it in the plugin's test sources and
+ * implement [factory]. Override [sample] and [completionOffset] so the suite asks about text the
+ * tooling understands.
+ */
+abstract class ToolingConformance {
+    protected abstract val factory: ToolingFactory
+
+    protected open val language: String = "javascript"
+
+    /** Declaration files the workspace starts with. */
+    protected open val libs: List<ToolingFile> = emptyList()
+
+    /** A document the tooling can analyse. */
+    protected open val sample: ToolingFile = ToolingFile("/project/main.js", "const answer = 42\nanswer.")
+
+    /** Where completion is asked in [sample]. */
+    protected open val completionOffset: Int get() = sample.text.length
+
+    protected lateinit var harness: ToolingHarness
+
+    @Before
+    fun openHarness() {
+        harness = ToolingHarness(factory)
+        harness.tools.configure(ToolingWorkspace(language, libs = libs))
+        harness.tools.sync(ToolingChange(upserts = listOf(sample)))
+    }
+
+    @After
+    fun closeHarness() = harness.close()
+
+    @Test
+    fun aToolingAnswersAtLeastOneKindOfQuestion() {
+        assertTrue(harness.tools.capabilities.isNotEmpty(), "A tooling lists what it can answer in capabilities")
+    }
+
+    @Test
+    fun diagnosticsStayInsideTheText() {
+        if (ToolingCapability.DIAGNOSTICS !in harness.tools.capabilities) return
+        harness.tools.diagnostics(sample.path).forEach {
+            assertTrue(it.start in 0..it.end, "A diagnostic starts before it ends: $it")
+            assertTrue(it.end <= sample.text.length, "A diagnostic ends inside the text: $it")
+            assertTrue(it.message.isNotBlank(), "A diagnostic says what is wrong: $it")
+        }
+    }
+
+    @Test
+    fun completionsNameWhatTheyInsertAndReplaceTextBeforeTheCursor() {
+        if (ToolingCapability.COMPLETION !in harness.tools.capabilities) return
+        val offset = completionOffset
+        harness.tools.complete(sample.path, offset).forEach {
+            assertTrue(it.label.isNotBlank(), "A completion has a label: $it")
+            val start = it.replaceStart ?: offset
+            val end = it.replaceEnd ?: offset
+            assertTrue(start in 0..end && end <= sample.text.length, "A completion replaces text inside the file: $it")
+        }
+    }
+
+    @Test
+    fun aFileCanBeRemovedAndSentAgain() {
+        harness.tools.sync(ToolingChange(removes = listOf(sample.path)))
+        harness.tools.sync(ToolingChange(upserts = listOf(sample)))
+        if (ToolingCapability.DIAGNOSTICS in harness.tools.capabilities) harness.tools.diagnostics(sample.path)
+    }
+
+    @Test
+    fun aQuestionAboutAnUnknownFileDoesNotEndTheSession() {
+        try {
+            if (ToolingCapability.DIAGNOSTICS in harness.tools.capabilities) harness.tools.diagnostics("/project/unknown.js")
+            if (ToolingCapability.COMPLETION in harness.tools.capabilities) harness.tools.complete("/project/unknown.js", 0)
+        } catch (_: CallException) {
+            // Refusing is allowed; the next question must still be answered.
+        }
+        if (ToolingCapability.DIAGNOSTICS in harness.tools.capabilities) harness.tools.diagnostics(sample.path)
+    }
+
+    @Test
+    fun startingOverKeepsTheSessionWorking() {
+        harness.tools.configure(ToolingWorkspace(language, libs = libs))
+        harness.tools.sync(ToolingChange(upserts = listOf(sample)))
+        if (ToolingCapability.DIAGNOSTICS in harness.tools.capabilities) harness.tools.diagnostics(sample.path)
+        assertEquals(emptyList(), harness.errors, "Nothing is reported as a failure no request waits on")
+    }
+}
diff --git a/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingHarness.kt b/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingHarness.kt
new file mode 100644
index 0000000..3c93ddf
--- /dev/null
+++ b/tck/src/main/kotlin/com/xfl/msgbot/plugin/tck/ToolingHarness.kt
@@ -0,0 +1,55 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.tck
+
+import com.xfl.msgbot.plugin.api.remote.RemoteLanguageTools
+import com.xfl.msgbot.plugin.api.remote.ToolingEndpoint
+import com.xfl.msgbot.plugin.api.rpc.LoopbackTransport
+import com.xfl.msgbot.plugin.api.tooling.LanguageTools
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
+import com.xfl.msgbot.plugin.api.tooling.ToolingHost
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+
+/**
+ * Runs tooling the way the host runs a plugin's: behind a [ToolingEndpoint], reached through
+ * [RemoteLanguageTools] over a loopback transport. [files] is what the tooling may read from the host.
+ */
+class ToolingHarness(
+    factory: ToolingFactory,
+    val files: MutableMap<String, String> = linkedMapOf(),
+) : AutoCloseable {
+    val errors = CopyOnWriteArrayList<String>()
+
+    private val transports = LoopbackTransport.pair()
+    private val endpoint = ToolingEndpoint(transports.second, factory)
+    private val reads = Executors.newCachedThreadPool { r -> Thread(r, "tooling-harness-reads").apply { isDaemon = true } }
+
+    /** The tooling as the host sees it; its capabilities come from the plugin's hello. */
+    val tools: LanguageTools =
+        RemoteLanguageTools.connect(
+            transports.first,
+            object : ToolingHost {
+                override fun read(path: String): String? = files[path]
+
+                override fun list(path: String): List<String>? =
+                    files.keys
+                        .filter { it.startsWith("$path/") }
+                        .map { it.removePrefix("$path/").substringBefore('/') }
+                        .distinct()
+                        .takeIf { it.isNotEmpty() }
+            },
+            reads,
+            timeoutMs = 5_000,
+            onError = { errors += it },
+        )
+
+    override fun close() {
+        tools.close()
+        endpoint.close()
+        reads.shutdownNow()
+    }
+}
diff --git a/tck/src/test/kotlin/com/xfl/msgbot/plugin/tck/ExampleToolingConformanceTest.kt b/tck/src/test/kotlin/com/xfl/msgbot/plugin/tck/ExampleToolingConformanceTest.kt
new file mode 100644
index 0000000..66c13e7
--- /dev/null
+++ b/tck/src/test/kotlin/com/xfl/msgbot/plugin/tck/ExampleToolingConformanceTest.kt
@@ -0,0 +1,43 @@
+/*
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * Copyright (C) 2026 MessengerBotTeam
+ */
+
+package com.xfl.msgbot.plugin.tck
+
+import com.xfl.msgbot.plugin.api.tooling.LanguageTools
+import com.xfl.msgbot.plugin.api.tooling.ToolCompletion
+import com.xfl.msgbot.plugin.api.tooling.ToolDiagnostic
+import com.xfl.msgbot.plugin.api.tooling.ToolSeverity
+import com.xfl.msgbot.plugin.api.tooling.ToolingCapability
+import com.xfl.msgbot.plugin.api.tooling.ToolingChange
+import com.xfl.msgbot.plugin.api.tooling.ToolingFactory
+import com.xfl.msgbot.plugin.api.tooling.ToolingWorkspace
+
+class ExampleToolingConformanceTest : ToolingConformance() {
+    private class Todos : LanguageTools {
+        private val texts = linkedMapOf<String, String>()
+
+        override val capabilities = setOf(ToolingCapability.DIAGNOSTICS, ToolingCapability.COMPLETION)
+
+        override fun configure(workspace: ToolingWorkspace) = texts.clear()
+
+        override fun sync(change: ToolingChange) {
+            change.removes.forEach { texts.remove(it) }
+            change.upserts.forEach { texts[it.path] = it.text }
+        }
+
+        override fun diagnostics(path: String): List<ToolDiagnostic> {
+            val text = texts[path] ?: return emptyList()
+            val at = text.indexOf("TODO")
+            return if (at < 0) emptyList() else listOf(ToolDiagnostic(at, at + 4, ToolSeverity.HINT, "A todo"))
+        }
+
+        override fun complete(
+            path: String,
+            offset: Int,
+        ): List<ToolCompletion> = listOf(ToolCompletion("answer", "variable", replaceStart = offset, replaceEnd = offset))
+    }
+
+    override val factory = ToolingFactory { Todos() }
+}

From 11ea7add343b38e37d6e825f612d5fbe5f237c30 Mon Sep 17 00:00:00 2001
From: "nenka.lab" <mail@zabocho.dev>
Date: Wed, 7 Oct 2026 14:20:34 +0900
Subject: [PATCH 2/2] feat: let configuring a tooling take longer than a
 question

---
 .../plugin/api/remote/RemoteLanguageTools.kt  |  8 +++++--
 .../plugin/api/remote/ToolingSessionTest.kt   | 21 +++++++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
index 6dfc343..0a62b88 100644
--- a/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
+++ b/contract/src/main/kotlin/com/xfl/msgbot/plugin/api/remote/RemoteLanguageTools.kt
@@ -33,6 +33,8 @@ import java.util.concurrent.Semaphore
  * answer within [timeoutMs]; [diagnostics], [complete], [hover] and [signatureHelp] carry that
  * deadline, so a plugin that falls behind skips the questions that are already stale.
  *
+ * [configure] may take [setupTimeoutMs] instead, since a tooling often loads its compiler there.
+ *
  * The plugin's reads of [files] run on [callExecutor], so a slow disk does not hold the transport.
  */
 class RemoteLanguageTools private constructor(
@@ -40,6 +42,7 @@ class RemoteLanguageTools private constructor(
     private val files: ToolingHost,
     private val callExecutor: Executor,
     private val timeoutMs: Long,
+    private val setupTimeoutMs: Long,
     maxPendingCalls: Int,
     private val onError: (String) -> Unit,
 ) : LanguageTools {
@@ -102,7 +105,7 @@ class RemoteLanguageTools private constructor(
     private val peer = RpcPeer(transport, handler, onError)
 
     override fun configure(workspace: ToolingWorkspace) {
-        peer.request(Wire.TOOLING_CONFIGURE, ToolingWire.workspace(workspace), timeoutMs).getOrThrow()
+        peer.request(Wire.TOOLING_CONFIGURE, ToolingWire.workspace(workspace), setupTimeoutMs).getOrThrow()
     }
 
     override fun sync(change: ToolingChange) {
@@ -148,10 +151,11 @@ class RemoteLanguageTools private constructor(
             files: ToolingHost,
             callExecutor: Executor,
             timeoutMs: Long = 10_000,
+            setupTimeoutMs: Long = 60_000,
             maxPendingCalls: Int = 32,
             onError: (String) -> Unit = {},
         ): RemoteLanguageTools {
-            val tools = RemoteLanguageTools(transport, files, callExecutor, timeoutMs, maxPendingCalls, onError)
+            val tools = RemoteLanguageTools(transport, files, callExecutor, timeoutMs, setupTimeoutMs, maxPendingCalls, onError)
             try {
                 val hello = Wire.checkHello(tools.peer.request(Wire.HELLO, Wire.hello(), Wire.HELLO_TIMEOUT_MS))
                 tools.capabilities =
diff --git a/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt b/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
index 77b444e..5f207a4 100644
--- a/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
+++ b/contract/src/test/kotlin/com/xfl/msgbot/plugin/api/remote/ToolingSessionTest.kt
@@ -200,4 +200,25 @@ class ToolingSessionTest {
             broken.close()
         }
     }
+
+    @Test
+    fun `configure may take longer than a question`() {
+        val pair = LoopbackTransport.pair()
+        val slow =
+            object : LanguageTools {
+                override val capabilities = setOf(ToolingCapability.DIAGNOSTICS)
+
+                override fun configure(workspace: ToolingWorkspace) = Thread.sleep(400)
+
+                override fun sync(change: ToolingChange) = Unit
+            }
+        val endpoint = ToolingEndpoint(pair.second, ToolingFactory { slow })
+        val patient = RemoteLanguageTools.connect(pair.first, host, callExecutor, timeoutMs = 100, setupTimeoutMs = 5_000)
+        try {
+            patient.configure(ToolingWorkspace("javascript"))
+        } finally {
+            patient.close()
+            endpoint.close()
+        }
+    }
 }