fix(khala): address review #132 — reuse nerve-core Result, RETURNING for appendMessage, configurable timeout

- Remove duplicate result.ts, import Result/ok/err from @uncaged/nerve-core
- appendMessage uses INSERT...RETURNING instead of INSERT+SELECT
- CloudRole.timeoutSeconds: per-role timeout (defaults to 300s)
- TODO comments for rate limiting and capacity sensing

packages/khala/package.json

@@ -10,6 +10,7 @@
     "check": "biome check ."
   },
   "dependencies": {
+    "@uncaged/nerve-core": "workspace:*",
     "hono": "^4.7.0",
     "jsonata": "^2.0.5",
     "ulidx": "^2.4.1"

packages/khala/src/__tests__/result.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect } from "vitest";
-import { ok, err } from "../result.js";
+import { err, ok } from "@uncaged/nerve-core";
+import { describe, expect, it } from "vitest";
 
 describe("Result", () => {
   it("ok wraps a value", () => {

packages/khala/src/db.ts

@@ -1,6 +1,6 @@
+import type { Result } from "@uncaged/nerve-core";
+import { err, ok } from "@uncaged/nerve-core";
 import { type ULID, monotonicFactory } from "ulidx";
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
 import type { Agent, GetThreadMessagesOpts, Message, Task, Thread } from "./types.js";
 
 const generateUlid = monotonicFactory((): number => Date.now());
@@ -88,19 +88,16 @@ export async function appendMessage(
   step: number,
   agentId: string | null,
 ): Promise<Message> {
-  await db
+  const row = await db
     .prepare(
       `INSERT INTO messages (thread_id, role, content, meta, step, agent_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`,
+       VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+       RETURNING *`,
     )
     .bind(threadId, role, content, meta, step, agentId)
-    .run();
-  const row = await db
-    .prepare("SELECT * FROM messages WHERE thread_id = ? AND step = ? ORDER BY id DESC LIMIT 1")
-    .bind(threadId, step)
     .first<MessageRow>();
   if (!row) {
-    throw new Error("appendMessage: row not found after insert");
+    throw new Error("appendMessage: INSERT RETURNING returned no row");
   }
   return rowToMessage(row);
 }

packages/khala/src/index.ts

@@ -97,6 +97,7 @@ app.get("/tasks", agentAuth, async (c) => {
 });
 
 // Claim a task
+// TODO(#132): Add max_concurrent_claims per agent to prevent greedy claiming
 app.post("/tasks/:id/claim", agentAuth, async (c) => {
   const taskId = c.req.param("id");
   const agentId = c.get("agentId");

packages/khala/src/moderator.ts

@@ -1,6 +1,6 @@
+import type { Result } from "@uncaged/nerve-core";
+import { err, ok } from "@uncaged/nerve-core";
 import jsonata from "jsonata";
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
 
 export type ModeratorDecision = { role: string };
 

packages/khala/src/result.ts

@@ -1,9 +0,0 @@
-export type Result<T, E = string> = { ok: true; value: T } | { ok: false; error: E };
-
-export function ok<T>(value: T): Result<T, never> {
-  return { ok: true, value };
-}
-
-export function err<E = string>(error: E): Result<never, E> {
-  return { ok: false, error };
-}

packages/khala/src/routes/admin.ts

@@ -1,8 +1,8 @@
+import type { Result } from "@uncaged/nerve-core";
 import { Hono } from "hono";
 import { requireAdmin, sha256Hex } from "../auth.js";
 import { deleteAgent, listAgents, registerAgent } from "../db.js";
 import type { KhalaBindings } from "../env.js";
-import type { Result } from "../result.js";
 
 const admin = new Hono<{ Bindings: KhalaBindings }>();
 
@@ -21,6 +21,7 @@ admin.get("/agents", async (c) => {
   return c.json({ agents: [...agents] });
 });
 
+// TODO(#132): Add rate limiting for agent registration endpoint
 admin.post("/agents", async (c) => {
   if (!requireAdmin(c)) {
     return c.json({ error: "unauthorized" }, 401);

packages/khala/src/thread-do.ts

@@ -87,7 +87,7 @@ export class ThreadDO {
       );
       return { ok: true };
     }
-    await createTask(db, threadId, role, r.prompt, 300);
+    await createTask(db, threadId, role, r.prompt, r.timeoutSeconds ?? 300);
     return { ok: true };
   }
 

packages/khala/src/workflows.ts

@@ -1,5 +1,7 @@
 export type CloudRole = {
   prompt: string;
+  /** Turn timeout in seconds. Defaults to 300. */
+  timeoutSeconds: number | null;
 };
 
 export type CloudWorkflowDef = {

packages/khala/src/workflows/ping-pong.ts

@@ -3,8 +3,8 @@ import { type CloudWorkflowDef, registerWorkflow } from "../workflows.js";
 const pingPong: CloudWorkflowDef = {
   name: "ping-pong",
   roles: {
-    pinger: { prompt: "Send the literal word ping" },
-    ponger: { prompt: "Send the literal word pong" },
+    pinger: { prompt: "Send the literal word ping", timeoutSeconds: null },
+    ponger: { prompt: "Send the literal word pong", timeoutSeconds: null },
   },
   moderator: `$count(steps) >= 6 ? { "role": "__end__" } : $count(steps) % 2 = 0 ? { "role": "pinger" } : { "role": "ponger" }`,
 };

pnpm-lock.yaml

@@ -86,6 +86,9 @@ importers:
 
   packages/khala:
     dependencies:
+      '@uncaged/nerve-core':
+        specifier: workspace:*
+        version: link:../core
       hono:
         specifier: ^4.7.0
         version: 4.12.15