@jiggai/kitchen 0.1.12 → 0.2.0

package/src/app/api/__tests__/teams-workflows-route.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { GET, POST, DELETE } from "../teams/workflows/route";
+
+vi.mock("@/lib/workflows/storage", () => ({
+  listWorkflows: vi.fn(),
+  readWorkflow: vi.fn(),
+  writeWorkflow: vi.fn(),
+  deleteWorkflow: vi.fn(),
+}));
+
+import { listWorkflows, readWorkflow, writeWorkflow, deleteWorkflow } from "@/lib/workflows/storage";
+
+describe("api teams workflows route", () => {
+  beforeEach(() => {
+    vi.mocked(listWorkflows).mockReset();
+    vi.mocked(readWorkflow).mockReset();
+    vi.mocked(writeWorkflow).mockReset();
+    vi.mocked(deleteWorkflow).mockReset();
+  });
+
+  it("GET returns 400 when teamId missing", async () => {
+    const res = await GET(new Request("https://test"));
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("teamId is required");
+  });
+
+  it("GET returns 200 with list when no id", async () => {
+    vi.mocked(listWorkflows).mockResolvedValue({ ok: true, dir: "/tmp", files: ["a.workflow.json"] });
+    const res = await GET(new Request("https://test?teamId=team1"));
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+    expect(json.files).toEqual(["a.workflow.json"]);
+    expect(listWorkflows).toHaveBeenCalledWith("team1");
+  });
+
+  it("GET returns 200 with workflow when id provided", async () => {
+    const wf = { id: "wf1", name: "Test", nodes: [], edges: [] };
+    vi.mocked(readWorkflow).mockResolvedValue({ ok: true, path: "/home/test/wf1.workflow.json", workflow: wf });
+    const res = await GET(new Request("https://test?teamId=team1&id=wf1"));
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+    expect(json.workflow).toEqual(wf);
+    expect(readWorkflow).toHaveBeenCalledWith("team1", "wf1");
+  });
+
+  it("POST returns 400 when teamId missing", async () => {
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ workflow: { id: "wf1", name: "Test", nodes: [], edges: [] } }),
+      })
+    );
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("teamId is required");
+  });
+
+  it("POST returns 400 when workflow invalid", async () => {
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ teamId: "team1", workflow: {} }),
+      })
+    );
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toMatch(/workflow.*required/i);
+  });
+
+  it("POST returns 200 when workflow valid", async () => {
+    const wf = { id: "wf1", name: "Test", nodes: [], edges: [] };
+    vi.mocked(writeWorkflow).mockResolvedValue({ ok: true, path: "/home/test/wf1.workflow.json" });
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ teamId: "team1", workflow: wf }),
+      })
+    );
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+    expect(writeWorkflow).toHaveBeenCalledWith("team1", expect.objectContaining({ id: "wf1", name: "Test" }));
+  });
+
+  it("DELETE returns 400 when teamId missing", async () => {
+    const res = await DELETE(new Request("https://test"));
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("teamId is required");
+  });
+
+  it("DELETE returns 400 when id missing", async () => {
+    const res = await DELETE(new Request("https://test?teamId=team1"));
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("id is required");
+  });
+
+  it("DELETE returns 200 when valid", async () => {
+    vi.mocked(deleteWorkflow).mockResolvedValue({ ok: true, path: "/home/test/wf1.workflow.json", existed: true });
+    const res = await DELETE(new Request("https://test?teamId=team1&id=wf1"));
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+    expect(deleteWorkflow).toHaveBeenCalledWith("team1", "wf1");
+  });
+});

package/src/app/api/__tests__/tickets-move-route.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { POST } from "../tickets/move/route";
+
+vi.mock("@/lib/openclaw", () => ({ runOpenClaw: vi.fn() }));
+
+import { runOpenClaw } from "@/lib/openclaw";
+
+describe("api tickets move route", () => {
+  beforeEach(() => {
+    vi.mocked(runOpenClaw).mockReset();
+  });
+
+  it("returns 400 when ticket missing", async () => {
+    const res = await POST(new Request("https://test", { method: "POST", body: JSON.stringify({}) }));
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("Missing ticket");
+  });
+
+  it("returns 400 when destination invalid", async () => {
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ ticket: "T-1", to: "invalid" }),
+      })
+    );
+    expect(res.status).toBe(400);
+    const json = await res.json();
+    expect(json.error).toBe("Invalid destination stage");
+  });
+
+  it("returns 200 when move succeeds", async () => {
+    vi.mocked(runOpenClaw).mockResolvedValue({ ok: true, exitCode: 0, stdout: "", stderr: "" });
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ ticket: "T-1", to: "in-progress" }),
+      })
+    );
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+    expect(runOpenClaw).toHaveBeenCalledWith(
+      expect.arrayContaining(["recipes", "move-ticket", "--ticket", "T-1", "--to", "in-progress"])
+    );
+  });
+
+  it("returns 500 when exec fails", async () => {
+    vi.mocked(runOpenClaw).mockRejectedValue(new Error("Command failed"));
+    const res = await POST(
+      new Request("https://test", {
+        method: "POST",
+        body: JSON.stringify({ ticket: "T-1", to: "done" }),
+      })
+    );
+    expect(res.status).toBe(500);
+    const json = await res.json();
+    expect(json.error).toBe("Command failed");
+  });
+});

package/src/app/api/agents/[id]/route.ts

@@ -5,22 +5,44 @@ import { NextResponse } from "next/server";
 import { runOpenClaw } from "@/lib/openclaw";
 import { parseTeamRoleWorkspace } from "@/lib/agent-workspace";
 
+async function resolveAgentWorkspace(agentId: string): Promise<string | null> {
+  try {
+    const { stdout } = await runOpenClaw(["agents", "list", "--json"]);
+    const list = JSON.parse(stdout) as Array<{ id: string; workspace?: string }>;
+    const agent = list.find((a) => a.id === agentId);
+    return agent?.workspace ? String(agent.workspace) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function moveTeamRoleToTrashOrRemove(info: {
+  teamDir: string;
+  role: string;
+  roleDir: string;
+}): Promise<void> {
+  const trashDir = path.join(info.teamDir, ".trash", "roles");
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const dst = path.join(trashDir, `${info.role}-${ts}`);
+  try {
+    await fs.mkdir(trashDir, { recursive: true });
+    await fs.rename(info.roleDir, dst);
+  } catch {
+    try {
+      await fs.rm(info.roleDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+}
+
 export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   try {
     const { id } = await params;
     const agentId = String(id ?? "").trim();
     if (!agentId) return NextResponse.json({ ok: false, error: "agent id is required" }, { status: 400 });
 
-    // Resolve workspace BEFORE deleting (after deletion it may disappear from list).
-    let workspace: string | null = null;
-    try {
-      const { stdout } = await runOpenClaw(["agents", "list", "--json"]);
-      const list = JSON.parse(stdout) as Array<{ id: string; workspace?: string }>;
-      const agent = list.find((a) => a.id === agentId);
-      workspace = agent?.workspace ? String(agent.workspace) : null;
-    } catch {
-      workspace = null;
-    }
+    const workspace = await resolveAgentWorkspace(agentId);
 
     const result = await runOpenClaw(["agents", "delete", agentId, "--force", "--json"]);
     if (!result.ok) {
@@ -42,27 +64,9 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
       parsed = null;
     }
 
-    // If this was a team role agent, also remove its role directory.
-    // Safer than rm: move to a team-local .trash folder.
     if (workspace) {
       const info = parseTeamRoleWorkspace(workspace);
-      if (info.kind === "teamRole") {
-        const trashDir = path.join(info.teamDir, ".trash", "roles");
-        const ts = new Date().toISOString().replace(/[:.]/g, "-");
-        const dst = path.join(trashDir, `${info.role}-${ts}`);
-        try {
-          await fs.mkdir(trashDir, { recursive: true });
-          // Only move if the dir exists.
-          await fs.rename(info.roleDir, dst);
-        } catch {
-          // If rename fails (cross-device / missing), fall back to best-effort recursive removal.
-          try {
-            await fs.rm(info.roleDir, { recursive: true, force: true });
-          } catch {
-            // ignore
-          }
-        }
-      }
+      if (info.kind === "teamRole") await moveTeamRoleToTrashOrRemove(info);
     }
 
     return NextResponse.json({ ok: true, result: parsed ?? result.stdout });

package/src/app/api/agents/add/route.ts

@@ -1,10 +1,10 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 
 import { NextResponse } from "next/server";
 
 import { getKitchenApi } from "@/lib/kitchen-api";
+import { teamDirFromBaseWorkspace } from "@/lib/paths";
 
 function normalizeAgentId(id: string) {
   const s = id.trim();
@@ -15,11 +15,30 @@ function normalizeAgentId(id: string) {
   return s;
 }
 
+function buildAgentEntry(
+  body: { newAgentId?: string; agentId?: string; name?: string; emoji?: string; theme?: string; avatar?: string; model?: string },
+  newAgentId: string,
+  newWorkspace: string
+): Record<string, unknown> {
+  const identity: Record<string, unknown> = {};
+  if (typeof body.name === "string" && body.name.trim()) identity.name = body.name.trim();
+  if (typeof body.theme === "string" && body.theme.trim()) identity.theme = body.theme.trim();
+  if (typeof body.emoji === "string" && body.emoji.trim()) identity.emoji = body.emoji.trim();
+  if (typeof body.avatar === "string" && body.avatar.trim()) identity.avatar = body.avatar.trim();
+
+  return {
+    id: newAgentId,
+    workspace: newWorkspace,
+    ...(body.model ? { model: body.model } : {}),
+    identity,
+  };
+}
+
 export async function POST(req: Request) {
   try {
     const body = (await req.json()) as {
       newAgentId?: string;
-      agentId?: string; // legacy/compat: some callers send agentId
+      agentId?: string;
       name?: string;
       emoji?: string;
       theme?: string;
@@ -31,46 +50,32 @@ export async function POST(req: Request) {
     const newAgentId = normalizeAgentId(String(body.newAgentId ?? body.agentId ?? ""));
     const overwrite = Boolean(body.overwrite);
 
-    const configPath = path.join(os.homedir(), ".openclaw", "openclaw.json");
-    if (!configPath.trim()) {
-      return NextResponse.json({ ok: false, error: "Could not resolve config path" }, { status: 500 });
+    if (!process.env.HOME) {
+      return NextResponse.json({ ok: false, error: "HOME is not set" }, { status: 500 });
     }
 
+    const configPath = path.join(process.env.HOME, ".openclaw", "openclaw.json");
     const raw = await fs.readFile(configPath, "utf8");
     const cfg = JSON.parse(raw) as {
       agents?: { defaults?: { workspace?: string }; list?: Array<Record<string, unknown>> };
     };
 
-  const baseWorkspace = String(cfg?.agents?.defaults?.workspace ?? "").trim();
-  if (!baseWorkspace) {
-    return NextResponse.json({ ok: false, error: "agents.defaults.workspace not set" }, { status: 500 });
-  }
-
-  const newWorkspace = path.resolve(baseWorkspace, "..", `workspace-${newAgentId}`);
-
-  const agentsList: Array<Record<string, unknown>> = Array.isArray(cfg?.agents?.list)
-    ? (cfg.agents?.list as Array<Record<string, unknown>>)
-    : [];
-  const exists = agentsList.some((a) => String(a?.id ?? "").toLowerCase() === newAgentId.toLowerCase());
-  if (exists && !overwrite) {
-    return NextResponse.json({ ok: false, error: `Agent already exists: ${newAgentId}` }, { status: 409 });
-  }
+    const baseWorkspace = String(cfg?.agents?.defaults?.workspace ?? "").trim();
+    if (!baseWorkspace) {
+      return NextResponse.json({ ok: false, error: "agents.defaults.workspace not set" }, { status: 500 });
+    }
 
-  const nextEntry: Record<string, unknown> = {
-    id: newAgentId,
-    workspace: newWorkspace,
-    ...(body.model ? { model: body.model } : {}),
-    identity: {
-      ...(typeof body.name === "string" && body.name.trim() ? { name: body.name.trim() } : {}),
-      ...(typeof body.theme === "string" && body.theme.trim() ? { theme: body.theme.trim() } : {}),
-      ...(typeof body.emoji === "string" && body.emoji.trim() ? { emoji: body.emoji.trim() } : {}),
-      ...(typeof body.avatar === "string" && body.avatar.trim() ? { avatar: body.avatar.trim() } : {}),
-    },
-  };
+    const newWorkspace = teamDirFromBaseWorkspace(baseWorkspace, newAgentId);
+    const agentsList: Array<Record<string, unknown>> = Array.isArray(cfg?.agents?.list) ? cfg.agents.list : [];
+    const exists = agentsList.some((a) => String(a?.id ?? "").toLowerCase() === newAgentId.toLowerCase());
+    if (exists && !overwrite) {
+      return NextResponse.json({ ok: false, error: `Agent already exists: ${newAgentId}` }, { status: 409 });
+    }
 
-  const nextList = exists
-    ? agentsList.map((a) => (String(a?.id ?? "").toLowerCase() === newAgentId.toLowerCase() ? nextEntry : a))
-    : [...agentsList, nextEntry];
+    const nextEntry = buildAgentEntry(body, newAgentId, newWorkspace);
+    const nextList = exists
+      ? agentsList.map((a) => (String(a?.id ?? "").toLowerCase() === newAgentId.toLowerCase() ? nextEntry : a))
+      : [...agentsList, nextEntry];
 
   // Ensure workspace directory exists and seed IDENTITY.md for clarity.
   await fs.mkdir(newWorkspace, { recursive: true });

package/src/app/api/agents/file/route.ts

@@ -1,55 +1,42 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { NextResponse } from "next/server";
-import { runOpenClaw } from "@/lib/openclaw";
-
-type AgentListItem = { id: string; workspace?: string };
-
-async function resolveAgentWorkspace(agentId: string) {
-  const { stdout } = await runOpenClaw(["agents", "list", "--json"]);
-  const list = JSON.parse(stdout) as AgentListItem[];
-  const agent = list.find((a) => a.id === agentId);
-  if (!agent?.workspace) throw new Error(`Agent workspace not found for ${agentId}`);
-  return agent.workspace;
-}
-
-function assertSafeName(name: string) {
-  const n = name.replace(/\\/g, "/");
-  if (!n || n.startsWith("/") || n.includes("..")) throw new Error("Invalid file name");
-  return n;
-}
+import { errorMessage } from "@/lib/errors";
+import { assertSafeRelativeFileName } from "@/lib/paths";
+import { getAgentContextFromBody, getAgentContextFromQuery } from "@/lib/api-route-helpers";
 
 export async function GET(req: Request) {
+  const ctx = await getAgentContextFromQuery(req);
+  if (ctx instanceof NextResponse) return ctx;
+  const { agentId, ws } = ctx;
+
   const { searchParams } = new URL(req.url);
-  const agentId = String(searchParams.get("agentId") ?? "").trim();
   const name = String(searchParams.get("name") ?? "").trim();
-  if (!agentId) return NextResponse.json({ ok: false, error: "agentId is required" }, { status: 400 });
   if (!name) return NextResponse.json({ ok: false, error: "name is required" }, { status: 400 });
 
-  const ws = await resolveAgentWorkspace(agentId);
-  const safe = assertSafeName(name);
+  const safe = assertSafeRelativeFileName(name);
   const filePath = path.join(ws, safe);
 
   try {
     const content = await fs.readFile(filePath, "utf8");
     return NextResponse.json({ ok: true, agentId, workspace: ws, name: safe, filePath, content });
   } catch (e: unknown) {
-    return NextResponse.json({ ok: false, error: e instanceof Error ? e.message : String(e) }, { status: 404 });
+    return NextResponse.json({ ok: false, error: errorMessage(e) }, { status: 404 });
   }
 }
 
 export async function PUT(req: Request) {
   const body = (await req.json()) as { agentId?: string; name?: string; content?: string };
-  const agentId = String(body.agentId ?? "").trim();
   const name = String(body.name ?? "").trim();
   const content = typeof body.content === "string" ? body.content : null;
-
-  if (!agentId) return NextResponse.json({ ok: false, error: "agentId is required" }, { status: 400 });
   if (!name) return NextResponse.json({ ok: false, error: "name is required" }, { status: 400 });
   if (content === null) return NextResponse.json({ ok: false, error: "content is required" }, { status: 400 });
 
-  const ws = await resolveAgentWorkspace(agentId);
-  const safe = assertSafeName(name);
+  const ctx = await getAgentContextFromBody(body);
+  if (ctx instanceof NextResponse) return ctx;
+  const { agentId, ws } = ctx;
+
+  const safe = assertSafeRelativeFileName(name);
   const filePath = path.join(ws, safe);
 
   await fs.mkdir(path.dirname(filePath), { recursive: true });

package/src/app/api/agents/files/route.ts

@@ -1,78 +1,23 @@
-import fs from "node:fs/promises";
-import path from "node:path";
 import { NextResponse } from "next/server";
-import { runOpenClaw } from "@/lib/openclaw";
-
-type AgentListItem = {
-  id: string;
-  identityName?: string;
-  workspace?: string;
-};
-
-async function resolveAgentWorkspace(agentId: string) {
-  const { stdout } = await runOpenClaw(["agents", "list", "--json"]);
-  const list = JSON.parse(stdout) as AgentListItem[];
-  const agent = list.find((a) => a.id === agentId);
-  if (!agent?.workspace) throw new Error(`Agent workspace not found for ${agentId}`);
-  return agent.workspace;
-}
+import { getAgentContextFromQuery, listWorkspaceFiles } from "@/lib/api-route-helpers";
 
 export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url);
-  const agentId = String(searchParams.get("agentId") ?? "").trim();
-  if (!agentId) return NextResponse.json({ ok: false, error: "agentId is required" }, { status: 400 });
-
-  const ws = await resolveAgentWorkspace(agentId);
+  const ctx = await getAgentContextFromQuery(req);
+  if (ctx instanceof NextResponse) return ctx;
+  const { agentId, ws } = ctx;
 
-  // Required vs optional classification to avoid "missing" noise.
-  const candidates: Array<{ name: string; required: boolean; rationale: string }> = [
+  const candidates = [
     { name: "SOUL.md", required: true, rationale: "Agent persona/instructions" },
     { name: "AGENTS.md", required: true, rationale: "Agent operating rules" },
     { name: "TOOLS.md", required: true, rationale: "Agent local notes" },
-
     { name: "STATUS.md", required: false, rationale: "Optional current status snapshot" },
     { name: "NOTES.md", required: false, rationale: "Optional scratchpad" },
     { name: "IDENTITY.md", required: false, rationale: "Optional identity (name/emoji/avatar)" },
     { name: "USER.md", required: false, rationale: "Optional user profile" },
     { name: "HEARTBEAT.md", required: false, rationale: "Optional periodic checklist" },
+    { name: "MEMORY.md", required: false, rationale: "Optional curated memory" },
   ];
 
-  const files = await Promise.all(
-    candidates.map(async (c) => {
-      const p = path.join(ws, c.name);
-      try {
-        const st = await fs.stat(p);
-        return {
-          name: c.name,
-          required: c.required,
-          rationale: c.rationale,
-          path: p,
-          missing: false,
-          size: st.size,
-          updatedAtMs: st.mtimeMs,
-        };
-      } catch {
-        return { name: c.name, required: c.required, rationale: c.rationale, path: p, missing: true };
-      }
-    })
-  );
-
-  // Optional: MEMORY.md
-  try {
-    const p = path.join(ws, "MEMORY.md");
-    const st = await fs.stat(p);
-    files.push({
-      name: "MEMORY.md",
-      required: false,
-      rationale: "Optional curated memory",
-      path: p,
-      missing: false,
-      size: st.size,
-      updatedAtMs: st.mtimeMs,
-    });
-  } catch {
-    // ignore
-  }
-
+  const files = await listWorkspaceFiles(ws, candidates);
   return NextResponse.json({ ok: true, agentId, workspace: ws, files });
 }

package/src/app/api/agents/route.ts

@@ -1,15 +1,8 @@
 import { NextResponse } from "next/server";
-
+import { type AgentListItem } from "@/lib/agents";
+import { errorMessage } from "@/lib/errors";
 import { runOpenClaw } from "@/lib/openclaw";
 
-type AgentListItem = {
-  id: string;
-  identityName?: string;
-  workspace?: string;
-  model?: string;
-  isDefault?: boolean;
-};
-
 export async function GET() {
   try {
     const { stdout, stderr } = await runOpenClaw(["agents", "list", "--json"]);
@@ -21,7 +14,7 @@ export async function GET() {
     return NextResponse.json(
       {
         error: "Failed to list agents",
-        message: err instanceof Error ? err.message : String(err),
+        message: errorMessage(err),
       },
       { status: 500 },
     );

package/src/app/api/agents/skills/install/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from "next/server";
 import { runOpenClaw } from "@/lib/openclaw";
 import { parseTeamRoleWorkspace } from "@/lib/agent-workspace";
+import { installSkillErrorResponse } from "@/lib/api-route-helpers";
 
 export async function POST(req: Request) {
   const body = (await req.json()) as { agentId?: string; skill?: string };
@@ -27,20 +28,7 @@ export async function POST(req: Request) {
   }
 
   const res = await runOpenClaw(args);
-  if (!res.ok) {
-    const stdout = res.stdout?.trim();
-    const stderr = res.stderr?.trim();
-    return NextResponse.json(
-      {
-        ok: false,
-        error: stderr || stdout || `openclaw ${args.join(" ")} failed (exit=${res.exitCode})`,
-        stdout: res.stdout,
-        stderr: res.stderr,
-        scopeArgs: args,
-      },
-      { status: 500 },
-    );
-  }
+  if (!res.ok) return installSkillErrorResponse(args, res, { scopeArgs: args });
 
   return NextResponse.json({ ok: true, agentId, skill, scopeArgs: args, stdout: res.stdout, stderr: res.stderr });
 }

package/src/app/api/agents/skills/route.ts

@@ -1,30 +1,18 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { NextResponse } from "next/server";
-import { runOpenClaw } from "@/lib/openclaw";
 import { parseTeamRoleWorkspace } from "@/lib/agent-workspace";
-
-type AgentListItem = { id: string; workspace?: string };
-
-async function resolveAgentWorkspace(agentId: string) {
-  const { stdout } = await runOpenClaw(["agents", "list", "--json"]);
-  const list = JSON.parse(stdout) as AgentListItem[];
-  const agent = list.find((a) => a.id === agentId);
-  if (!agent?.workspace) throw new Error(`Agent workspace not found for ${agentId}`);
-  return agent.workspace;
-}
+import { getAgentContextFromQuery } from "@/lib/api-route-helpers";
+import { errorMessage } from "@/lib/errors";
 
 export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url);
-  const agentId = String(searchParams.get("agentId") ?? "").trim();
-  if (!agentId) return NextResponse.json({ ok: false, error: "agentId is required" }, { status: 400 });
-
-  const ws = await resolveAgentWorkspace(agentId);
+  const ctx = await getAgentContextFromQuery(req);
+  if (ctx instanceof NextResponse) return ctx;
+  const { agentId, ws } = ctx;
 
   const info = parseTeamRoleWorkspace(ws);
   const dirs: string[] = [path.join(ws, "skills")];
   if (info.kind === "teamRole") {
-    // If skills were installed at the team scope, surface them for the role agent too.
     dirs.push(path.join(info.teamDir, "skills"));
   }
 
@@ -36,7 +24,7 @@ export async function GET(req: Request) {
       const entries = await fs.readdir(skillsDir, { withFileTypes: true });
       for (const e of entries) if (e.isDirectory()) skills.add(e.name);
     } catch (e: unknown) {
-      notes.push(`${skillsDir}: ${e instanceof Error ? e.message : String(e)}`);
+      notes.push(`${skillsDir}: ${errorMessage(e)}`);
     }
   }
 

package/src/app/api/channels/bindings/route.ts

@@ -1,17 +1,8 @@
 import { NextResponse } from "next/server";
+import { errorMessage } from "@/lib/errors";
 import { gatewayConfigGet, gatewayConfigPatch } from "@/lib/gateway";
-
-function safeJsonParse(raw: string): unknown {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return Boolean(v) && typeof v === "object" && !Array.isArray(v);
-}
+import { safeJsonParse } from "@/lib/json";
+import { isRecord } from "@/lib/type-guards";
 
 export async function GET() {
   try {
@@ -21,7 +12,7 @@ export async function GET() {
     const channels = isRecord(root.channels) ? root.channels : {};
     return NextResponse.json({ ok: true, hash, channels });
   } catch (e: unknown) {
-    const msg = e instanceof Error ? e.message : String(e);
+    const msg = errorMessage(e);
     return NextResponse.json({ ok: false, error: msg }, { status: 500 });
   }
 }
@@ -49,7 +40,7 @@ export async function PUT(req: Request) {
     await gatewayConfigPatch({ channels: { [provider]: cfg } }, `ClawKitchen Channels upsert: ${provider}`);
     return NextResponse.json({ ok: true });
   } catch (e: unknown) {
-    const msg = e instanceof Error ? e.message : String(e);
+    const msg = errorMessage(e);
     return NextResponse.json({ ok: false, error: msg }, { status: 500 });
   }
 }
@@ -66,7 +57,7 @@ export async function DELETE(req: Request) {
     await gatewayConfigPatch({ channels: { [provider]: null } }, `ClawKitchen Channels delete: ${provider}`);
     return NextResponse.json({ ok: true });
   } catch (e: unknown) {
-    const msg = e instanceof Error ? e.message : String(e);
+    const msg = errorMessage(e);
     return NextResponse.json({ ok: false, error: msg }, { status: 500 });
   }
 }