@m6d/cortex-server 1.8.0 → 2.0.0

package/src/lib/graph/resolver.ts

@@ -6,14 +6,23 @@
  * or environment variables.
  */
 
-import type { EmbeddingModel } from "ai";
-import { embed } from "ai";
-import type { Neo4jClient } from "./neo4j.ts";
-import type { ConceptDef } from "./types.ts";
+import {
+    GRAPH_SCHEMA,
+    GRAPH_SCHEMA_VERSION,
+    type ConceptDef,
+    type EmbedFn,
+    type Neo4jClient,
+} from "@cortex/contracts/graph";
 
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
+// The graph's vocabulary, aliased short so the Cypher below still reads as Cypher.
+const { label: L, rel: R, prop: P } = GRAPH_SCHEMA;
+
+/**
+ * Seed data, not schema: the concept a project names to expose its generic
+ * service-request endpoints, which is why it stays here rather than in
+ * `schema.ts` — the seeder writes whatever concepts a domain declares.
+ */
+const SERVICE_REQUEST = "ServiceRequest";
 
 export type RerankerConfig = {
     url: string;
@@ -22,14 +31,10 @@ export type RerankerConfig = {
 
 export type ResolverConfig = {
     neo4j: Neo4jClient;
-    embeddingModel: EmbeddingModel;
+    embed: EmbedFn;
     reranker?: RerankerConfig;
 };
 
-// ---------------------------------------------------------------------------
-// Result types
-// ---------------------------------------------------------------------------
-
 type EndpointDependency = {
     depPath: string;
     depMethod: string;
@@ -39,6 +44,8 @@ type EndpointDependency = {
 
 type EndpointRelation = "read" | "write";
 
+type RelationType = typeof R.queriedVia | typeof R.mutatedVia;
+
 export type ResolvedEndpoint = {
     concept: string;
     relation: EndpointRelation;
@@ -68,13 +75,9 @@ export type ResolvedContext = {
     services: ResolvedService[];
 };
 
-// ---------------------------------------------------------------------------
-// Internal row types
-// ---------------------------------------------------------------------------
-
 type EndpointRow = {
     concept: string;
-    relationType: "QUERIED_VIA" | "MUTATED_VIA";
+    relationType: RelationType;
     name: string;
     path: string;
     method: string;
@@ -95,11 +98,63 @@ type ServiceRow = {
     rules: (string | null)[];
 };
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+/**
+ * Cleared only by a restart, which is also the only thing that can change which
+ * schema this process reads with. A re-seed under a running server is the case
+ * this misses, and re-seeding at the same version is the overwhelmingly common one.
+ */
+let versionChecked = false;
+
+/**
+ * `@m6d/cortex-cli` stamps the schema version it seeded onto the graph; this reads
+ * it back before any Cypher below runs. Lazily, on the first resolve rather than at
+ * boot, so a Neo4j that happens to be down cannot stop `serve()`.
+ */
+async function assertGraphVersion(neo4j: Neo4jClient) {
+    if (versionChecked) return;
+
+    const rows: unknown = await neo4j
+        .query(
+            `OPTIONAL MATCH (g:${L.marker}) WITH g LIMIT 1
+             OPTIONAL MATCH (c:${L.concept})
+             RETURN g.${P.version} AS version, count(c) AS concepts`,
+        )
+        .then(JSON.parse)
+        .catch(() => undefined);
+
+    // An unreachable graph answers with an error object rather than a row array.
+    // That is the resolve's own failure to report, not schema skew.
+    if (!Array.isArray(rows)) return;
+
+    // OPTIONAL MATCH answers a missing marker with `null`, not with a missing row.
+    const { version: stamped, concepts } =
+        (rows as { version?: number | null; concepts?: number }[])[0] ?? {};
+    if (stamped === GRAPH_SCHEMA_VERSION) {
+        versionChecked = true;
+        return;
+    }
+
+    // No stamp over an empty graph is a project mid-setup (Neo4j configured, seed
+    // not yet run), not skew: resolve as the empty context it is. Not cached, so
+    // the stamp is validated as soon as a seed lands.
+    if (stamped == null && (concepts ?? 0) === 0) return;
+
+    throw new Error(
+        [
+            stamped == null
+                ? `The Neo4j graph holds data but no schema stamp, and this server reads graph schema v${GRAPH_SCHEMA_VERSION}.`
+                : `The Neo4j graph was written with graph schema v${stamped}, and this server reads v${GRAPH_SCHEMA_VERSION}.`,
+            "Writer and reader disagree on the labels, relationships and property names, so retrieval would return empty or wrong results instead of failing.",
+            "Re-seed the graph with `bunx @m6d/cortex-cli graph seed`, or install the @m6d/cortex-server that matches the graph you have.",
+        ].join(" "),
+    );
+}
 
 export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
+    // Before the first query and outside the catch below: skew is invisible to
+    // every check further down, which is the whole reason it is checked here.
+    await assertGraphVersion(config.neo4j);
+
     const empty: ResolvedContext = {
         readEndpoints: [],
         writeEndpoints: [],
@@ -107,16 +162,13 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
     };
 
     try {
-        const { embedding } = await embed({
-            model: config.embeddingModel,
-            value: prompt,
-        });
+        const embedding = (await config.embed([prompt]))[0]!;
 
         const conceptsRaw = await config.neo4j.query(
-            `CALL db.index.vector.queryNodes('concept_embeddings', 10, $embedding)
+            `CALL db.index.vector.queryNodes('${GRAPH_SCHEMA.conceptEmbeddingsIndex}', 10, $embedding)
              YIELD node, score
              WHERE score > 0.3
-             RETURN node.name AS name, node.description AS description, score
+             RETURN node.${P.name} AS name, node.${P.description} AS description, score
              ORDER BY score DESC`,
             { embedding },
         );
@@ -139,74 +191,55 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
 
         const endpointsRaw = await config.neo4j.query(
             `UNWIND $names AS conceptName
-             MATCH (c:Concept {name: conceptName})-[:SPECIALIZES*0..3]->(ancestor:Concept)
+             MATCH (c:${L.concept} {${P.name}: conceptName})-[:${R.specializes}*0..3]->(ancestor:${L.concept})
              WITH conceptName, collect(DISTINCT ancestor) AS family
              UNWIND family AS related
-             MATCH (related)-[rel:QUERIED_VIA|MUTATED_VIA]->(e:Endpoint)
+             MATCH (related)-[rel:${R.queriedVia}|${R.mutatedVia}]->(e:${L.endpoint})
              WITH conceptName, related, rel, e
-             OPTIONAL MATCH (e)-[d:DEPENDS_ON]->(dep:Endpoint)
+             OPTIONAL MATCH (e)-[d:${R.dependsOn}]->(dep:${L.endpoint})
              WITH conceptName, related, rel, e,
                   collect(DISTINCT {
-                      depPath: dep.path,
-                      depMethod: dep.method,
-                      paramName: d.paramName,
-                      fromField: d.fromField
+                      depPath: dep.${P.path},
+                      depMethod: dep.${P.method},
+                      paramName: d.${P.paramName},
+                      fromField: d.${P.fromField}
                   }) AS dependencies
-             OPTIONAL MATCH (rEndpoint:Rule)-[:GOVERNS]->(e)
-             OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(related)
+             OPTIONAL MATCH (rEndpoint:${L.rule})-[:${R.governs}]->(e)
+             OPTIONAL MATCH (rConcept:${L.rule})-[:${R.governs}]->(related)
              RETURN conceptName AS concept,
                     type(rel) AS relationType,
-                    e.name AS name,
-                    e.path AS path,
-                    e.method AS method,
-                    e.params AS params,
-                    e.body AS body,
-                    e.response AS response,
-                    e.metadata AS metadata,
+                    e.${P.name} AS name,
+                    e.${P.path} AS path,
+                    e.${P.method} AS method,
+                    e.${P.params} AS params,
+                    e.${P.body} AS body,
+                    e.${P.response} AS response,
+                    e.${P.metadata} AS metadata,
                     dependencies,
-                    collect(DISTINCT rEndpoint.description) +
-                    collect(DISTINCT rConcept.description) AS rules`,
+                    collect(DISTINCT rEndpoint.${P.description}) +
+                    collect(DISTINCT rConcept.${P.description}) AS rules`,
             { names: conceptNames },
         );
 
         const endpointRows = asArray<EndpointRow>(JSON.parse(endpointsRaw));
-        const allEndpoints = dedupeEndpoints(
-            endpointRows.map(function (row) {
-                return {
-                    concept: row.concept,
-                    relation:
-                        row.relationType === "MUTATED_VIA" ? ("write" as const) : ("read" as const),
-                    name: row.name,
-                    path: row.path,
-                    method: row.method,
-                    params: row.params ?? "[]",
-                    body: row.body ?? "[]",
-                    response: row.response ?? "[]",
-                    metadata: row.metadata ?? "{}",
-                    dependencies: row.dependencies.filter(
-                        (dep): dep is EndpointDependency => dep.depPath != null,
-                    ),
-                    rules: row.rules.filter((rule): rule is string => Boolean(rule)),
-                };
-            }),
-        );
+        const allEndpoints = dedupeEndpoints(endpointRows.map(toResolvedEndpoint));
 
         const servicesRaw = await config.neo4j.query(
             `UNWIND $names AS conceptName
-             MATCH (c:Concept {name: conceptName})-[:SPECIALIZES*0..3]->(ancestor:Concept)
+             MATCH (c:${L.concept} {${P.name}: conceptName})-[:${R.specializes}*0..3]->(ancestor:${L.concept})
              WITH conceptName, collect(DISTINCT ancestor) AS family
              UNWIND family AS related
-             MATCH (related)-[:REQUESTED_VIA]->(svc:Service)
+             MATCH (related)-[:${R.requestedVia}]->(svc:${L.service})
              WITH conceptName, related, svc
-             OPTIONAL MATCH (rService:Rule)-[:GOVERNS]->(svc)
-             OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(related)
+             OPTIONAL MATCH (rService:${L.rule})-[:${R.governs}]->(svc)
+             OPTIONAL MATCH (rConcept:${L.rule})-[:${R.governs}]->(related)
              RETURN conceptName AS concept,
-                    svc.name AS serviceName,
-                    svc.builtInId AS builtInId,
-                    svc.description AS description,
-                    svc.metadata AS metadata,
-                    collect(DISTINCT rService.description) +
-                    collect(DISTINCT rConcept.description) AS rules`,
+                    svc.${P.name} AS serviceName,
+                    svc.${P.builtInId} AS builtInId,
+                    svc.${P.description} AS description,
+                    svc.${P.metadata} AS metadata,
+                    collect(DISTINCT rService.${P.description}) +
+                    collect(DISTINCT rConcept.${P.description}) AS rules`,
             { names: conceptNames },
         );
 
@@ -228,53 +261,34 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
         let servicingEndpoints: ResolvedEndpoint[] = [];
         if (services.length > 0) {
             const servicingRaw = await config.neo4j.query(
-                `MATCH (c:Concept {name: 'ServiceRequest'})-[rel:QUERIED_VIA|MUTATED_VIA]->(e:Endpoint)
-                 OPTIONAL MATCH (e)-[d:DEPENDS_ON]->(dep:Endpoint)
+                `MATCH (c:${L.concept} {${P.name}: '${SERVICE_REQUEST}'})-[rel:${R.queriedVia}|${R.mutatedVia}]->(e:${L.endpoint})
+                 OPTIONAL MATCH (e)-[d:${R.dependsOn}]->(dep:${L.endpoint})
                  WITH c, rel, e,
                       collect(DISTINCT {
-                          depPath: dep.path,
-                          depMethod: dep.method,
-                          paramName: d.paramName,
-                          fromField: d.fromField
+                          depPath: dep.${P.path},
+                          depMethod: dep.${P.method},
+                          paramName: d.${P.paramName},
+                          fromField: d.${P.fromField}
                       }) AS dependencies
-                 OPTIONAL MATCH (rEndpoint:Rule)-[:GOVERNS]->(e)
-                 OPTIONAL MATCH (rConcept:Rule)-[:GOVERNS]->(c)
-                 RETURN 'ServiceRequest' AS concept,
+                 OPTIONAL MATCH (rEndpoint:${L.rule})-[:${R.governs}]->(e)
+                 OPTIONAL MATCH (rConcept:${L.rule})-[:${R.governs}]->(c)
+                 RETURN '${SERVICE_REQUEST}' AS concept,
                         type(rel) AS relationType,
-                        e.name AS name,
-                        e.path AS path,
-                        e.method AS method,
-                        e.params AS params,
-                        e.body AS body,
-                        e.response AS response,
-                        e.metadata AS metadata,
+                        e.${P.name} AS name,
+                        e.${P.path} AS path,
+                        e.${P.method} AS method,
+                        e.${P.params} AS params,
+                        e.${P.body} AS body,
+                        e.${P.response} AS response,
+                        e.${P.metadata} AS metadata,
                         dependencies,
-                        collect(DISTINCT rEndpoint.description) +
-                        collect(DISTINCT rConcept.description) AS rules`,
+                        collect(DISTINCT rEndpoint.${P.description}) +
+                        collect(DISTINCT rConcept.${P.description}) AS rules`,
                 {},
             );
 
             servicingEndpoints = dedupeEndpoints(
-                asArray<EndpointRow>(JSON.parse(servicingRaw)).map(function (row) {
-                    return {
-                        concept: row.concept,
-                        relation:
-                            row.relationType === "MUTATED_VIA"
-                                ? ("write" as const)
-                                : ("read" as const),
-                        name: row.name,
-                        path: row.path,
-                        method: row.method,
-                        params: row.params ?? "[]",
-                        body: row.body ?? "[]",
-                        response: row.response ?? "[]",
-                        metadata: row.metadata ?? "{}",
-                        dependencies: row.dependencies.filter(
-                            (dep): dep is EndpointDependency => dep.depPath != null,
-                        ),
-                        rules: row.rules.filter((rule): rule is string => Boolean(rule)),
-                    };
-                }),
+                asArray<EndpointRow>(JSON.parse(servicingRaw)).map(toResolvedEndpoint),
             );
         }
 
@@ -291,14 +305,30 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
     }
 }
 
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
 function asArray<T>(value: unknown) {
     return Array.isArray(value) ? (value as T[]) : ([] as T[]);
 }
 
+/** Maps a Cypher row to an endpoint. The string defaults stand in for columns
+ *  Neo4j returns as null, which downstream JSON.parse calls would choke on. */
+function toResolvedEndpoint(row: EndpointRow) {
+    return {
+        concept: row.concept,
+        relation: row.relationType === R.mutatedVia ? ("write" as const) : ("read" as const),
+        name: row.name,
+        path: row.path,
+        method: row.method,
+        params: row.params ?? "[]",
+        body: row.body ?? "[]",
+        response: row.response ?? "[]",
+        metadata: row.metadata ?? "{}",
+        dependencies: row.dependencies.filter(
+            (dep): dep is EndpointDependency => dep.depPath != null,
+        ),
+        rules: row.rules.filter((rule): rule is string => Boolean(rule)),
+    } satisfies ResolvedEndpoint;
+}
+
 function dedupeEndpoints(endpoints: ResolvedEndpoint[]) {
     const seen = new Set<string>();
     const deduped: ResolvedEndpoint[] = [];

package/src/lib/index.ts

@@ -2,15 +2,21 @@
 export type {
     CortexConfig,
     CortexAgentDefinition,
+    ControlCenterConfig,
     KnowledgeConfig,
     DatabaseConfig,
+    RedisConfig,
     StorageConfig,
     PromptContext,
     ToolContext,
+    ToolSet,
     ToolSetFactory,
 } from "./config";
 export { defineAgent } from "./config";
 
+// Provider shape, so a consumer can name what it passes to the model helpers.
+export type { ProviderConfig } from "./ai/helpers";
+
 export type { ContextConfig, ThreadContextMeta } from "./ai/context/types";
 
 // Types consumers may need
@@ -28,12 +34,13 @@ export type {
 export { createRequestInterceptor } from "./ai/interceptors/request-interceptor";
 
 // Tools (consumers may register custom tools or use built-in ones)
-export { captureFilesTool } from "./ai/tools/capture-files.tool";
 export { createQueryGraphTool } from "./ai/tools/query-graph.tool";
 export { createExecuteCodeTool } from "./ai/tools/execute-code.tool";
 
-// Graph (consumers may use independently)
+// Graph (consumers may use independently). The contract itself lives in
+// @cortex/contracts/graph — see ./graph/index — and is re-exported through here.
 export * from "./graph/index";
 
-// WebSocket event types
-export type { WsEvent, ThreadTitleUpdatedEvent } from "./ws/index";
+// The wire contract, re-exported so consumers get it without a second import path.
+// Its home is @cortex/contracts/wire, which the client SDKs compile in too.
+export * from "@cortex/contracts/wire";

package/src/lib/redis.ts

@@ -0,0 +1,44 @@
+import { Redis } from "ioredis";
+
+/**
+ * The two long-lived connections everything Redis-backed shares. A subscriber
+ * connection cannot issue normal commands, so pub/sub listening gets its own;
+ * the publisher carries everything else (claims, stream appends, PUBLISH).
+ * Blocking stream reads never run on either — each reader duplicates its own
+ * connection, or one blocked XREAD would stall every claim and append behind it.
+ */
+export type RedisConnections = {
+    publisher: Redis;
+    subscriber: Redis;
+};
+
+/**
+ * Without an `error` listener ioredis raises unhandled-error events, which can
+ * crash the process — with one, a flapping or unreachable Redis becomes a log
+ * line while ioredis reconnects underneath.
+ */
+export function withRedisLogging(client: Redis, role: string) {
+    client.on("error", (error: unknown) => console.error(`[cortex-server] redis ${role}:`, error));
+    return client;
+}
+
+/**
+ * Cached per URL on `globalThis` so hot reloads and repeated `createCortex`
+ * calls reuse the connections instead of opening new ones each time.
+ */
+const store = globalThis as typeof globalThis & {
+    __cortexRedis?: Map<string, RedisConnections>;
+};
+
+export function getRedisConnections(url: string) {
+    store.__cortexRedis ??= new Map();
+    let connections = store.__cortexRedis.get(url);
+    if (!connections) {
+        connections = {
+            publisher: withRedisLogging(new Redis(url), "publisher"),
+            subscriber: withRedisLogging(new Redis(url), "subscriber"),
+        };
+        store.__cortexRedis.set(url, connections);
+    }
+    return connections;
+}

package/src/lib/routes/chat.ts

@@ -1,85 +1,114 @@
+import { EventType, chatParamsFromRequest, resumeServerSentEventsResponse } from "@tanstack/ai";
+import type { AbortRunResult } from "@cortex/contracts/wire";
 import { Hono } from "hono";
-import { zValidator } from "@hono/zod-validator";
-import z from "zod";
+import { bodyLimit } from "hono/body-limit";
 import { HTTPException } from "hono/http-exception";
-import type { CortexAppEnv } from "../types.ts";
-import { requireAuth } from "../auth/middleware.ts";
-import { stream } from "../ai/index.ts";
-import { subscribe, abortStream } from "../ai/active-streams.ts";
-import { notify } from "../ws/index.ts";
-import { toThreadSummary } from "../types.ts";
+import type { CortexAppEnv } from "@/types";
+import { requireAuth } from "@/auth/middleware";
+import { startTurn } from "@/ai/index";
+import { abortRun, getRunId, joinLog, offsetBelongsToRun } from "@/ai/active-runs";
+import { notify } from "@/ws/connections";
+import { requireOwnedThread } from "./owned-thread";
+import { toThreadSummary } from "@/types";
+
+const CHAT_BODY_MAX_BYTES = 1024 * 1024;
+
+/**
+ * The answer to "attach me to the run on this thread" when there is no longer
+ * one. An empty body would be the obvious reply, but the client reads every
+ * attach as a stream and treats a missing one as a transport failure — so the
+ * run is reported over, which is what actually happened, and the client settles
+ * the turn from the database like any other ending.
+ */
+function runEnded() {
+    const finished = { type: EventType.RUN_FINISHED, timestamp: Date.now() };
+
+    return new Response(`data: ${JSON.stringify(finished)}\n\n`, {
+        headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        },
+    });
+}
 
 export function createChatRoutes() {
     const app = new Hono<CortexAppEnv>();
 
-    app.post(
-        "/chat",
-        requireAuth,
-        zValidator(
-            "json",
-            z.object({
-                id: z.string(),
-                messages: z.array(z.unknown()),
-            }),
-        ),
-        async function (c) {
-            const config = c.get("agentConfig");
-            const agentId = c.get("agentId");
-            const { id: userId, token } = c.get("user");
-            const { messages, id: threadId } = c.req.valid("json");
-            const requestContext = config.resolveRequestContext
-                ? await config.resolveRequestContext(c.req.raw)
-                : {};
-
-            const thread = await config.db.threads.getById(userId, threadId);
-
-            if (!thread || thread.agentId !== agentId) {
-                throw new HTTPException(404, { message: "Not found" });
+    app.post("/chat", requireAuth, bodyLimit({ maxSize: CHAT_BODY_MAX_BYTES }), async function (c) {
+        const config = c.get("agentConfig");
+        const { id: userId, token } = c.get("user");
+
+        let params: Awaited<ReturnType<typeof chatParamsFromRequest>>;
+        try {
+            params = await chatParamsFromRequest(c.req.raw);
+        } catch (thrown) {
+            // The AG-UI validator rejects a malformed body by throwing the
+            // 400 it wants sent; Hono has no such convention, so return it.
+            if (thrown instanceof Response) return thrown;
+            throw thrown;
+        }
+
+        const thread = await requireOwnedThread(c, params.threadId);
+
+        // A dropped connection re-POSTs the same body with Last-Event-ID.
+        // The run is already producing into its log, so this replays from
+        // where the client left off rather than starting a second turn. A
+        // run that has since finished sends the client back to the messages
+        // endpoint, which by then holds everything the log would have.
+        const resumeOffset = c.req.header("Last-Event-ID");
+        if (resumeOffset) {
+            const runId = await getRunId(thread.id);
+            if (!runId) return runEnded();
+            if (!offsetBelongsToRun(resumeOffset, runId)) {
+                throw new HTTPException(400, { message: "Invalid resume offset" });
             }
 
-            return stream(messages, thread, userId, token, requestContext, config);
-        },
-    );
+            return resumeServerSentEventsResponse({
+                adapter: joinLog(thread.id, runId, resumeOffset),
+            });
+        }
+
+        const requestContext = config.resolveRequestContext
+            ? await config.resolveRequestContext(c.req.raw)
+            : {};
+
+        // Null means a stop beat the run to its own announcement; the run is
+        // over, which is what actually happened.
+        return (
+            (await startTurn(params, thread, userId, token, requestContext, config)) ?? runEnded()
+        );
+    });
 
+    /** Attaches a reload, a thread switch, or a second tab to the thread's live run. */
     app.get("/chat/:chatId/stream", requireAuth, async function (c) {
-        const config = c.get("agentConfig");
-        const agentId = c.get("agentId");
         const chatId = c.req.param("chatId");
-        const thread = await config.db.threads.getById(c.get("user").id, chatId);
-        if (!thread || thread.agentId !== agentId) {
-            throw new HTTPException(404, { message: "Not found" });
-        }
+        await requireOwnedThread(c, chatId);
 
-        const subscriberStream = subscribe(chatId);
-        if (!subscriberStream) {
-            return c.body(null, 204);
-        }
+        const runId = await getRunId(chatId);
+        if (!runId) return runEnded();
 
-        return new Response(subscriberStream.pipeThrough(new TextEncoderStream()), {
-            headers: {
-                "Content-Type": "text/event-stream",
-                "Cache-Control": "no-cache",
-                Connection: "keep-alive",
-            },
-        });
+        return resumeServerSentEventsResponse({ adapter: joinLog(chatId, runId) });
     });
 
     app.post("/chat/:chatId/abort", requireAuth, async function (c) {
-        const config = c.get("agentConfig");
         const agentId = c.get("agentId");
         const userId = c.get("user").id;
         const chatId = c.req.param("chatId");
-        const thread = await config.db.threads.getById(userId, chatId);
-        if (!thread || thread.agentId !== agentId) {
-            throw new HTTPException(404, { message: "Not found" });
-        }
+        const thread = await requireOwnedThread(c, chatId);
 
-        abortStream(chatId);
-        notify(userId, agentId, {
-            type: "thread:run-finished",
-            payload: { thread: toThreadSummary(thread, false) },
-        });
-        return c.body(null, 204);
+        // Only announce an ending that happened: the client's stop button can
+        // outlive the server run (it drains the durability log after the
+        // producer commits), and a run-finished for a run that already ended
+        // can land before its own run-started and pin the thread as running.
+        const aborted = await abortRun(chatId);
+        if (aborted) {
+            notify(userId, agentId, {
+                type: "thread:run-finished",
+                payload: { thread: toThreadSummary(thread, false) },
+            });
+        }
+        return c.json({ aborted } satisfies AbortRunResult);
     });
 
     return app;