fix(appkit): apply review feedback to agents plugin

PR #304 agentic review applied (P1 + cheap P2):

- Approval gate now honours the modern `effect` field (write/update/
  destructive), matching the documented contract on ToolAnnotations.
  Previously a tool authored with `effect: "destructive"` and no legacy
  `destructive: true` boolean bypassed the gate.
- Sub-agent tool calls share the parent's RunState, so the per-run
  tool-call budget and the destructive-tool approval gate apply to
  nested sub-agent calls — not only the top-level adapter.
- /invocations enforces `maxConcurrentStreamsPerUser`. Without this a
  client could bypass the cap by switching from /chat to /invocations.
- /cancel uses a Zod schema instead of a raw `as` cast, matching the
  validation pattern of the sibling routes.
- agents.reload() builds the registry into a fresh Map and only swaps
  on success. A malformed markdown file no longer wipes the live
  registry and breaks in-flight requests.
- consumeAdapterStream and normalizeToolResult are wired into the four
  call sites that previously inlined the same accumulation /
  serialization logic (top-level _streamAgent, runSubAgent,
  dispatchToolCall, runAgent).
- load-agents.ts uses fs.promises so reload() does not block the event
  loop.
- Pin js-yaml to 4.1.1 (drop the caret), matching the rest of appkit's
  pinned deps.

Tests cover the approval-gate `effect` matrix (destructive/write/update
trigger; read/undefined skip), the deny path, the shared budget across
top-level + sub-agent dispatches, and the /invocations rate-limit gate.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

packages/appkit/package.json

@@ -76,7 +76,7 @@
     "dotenv": "16.6.1",
     "express": "4.22.0",
     "get-port": "7.2.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "4.1.1",
     "obug": "2.1.1",
     "pg": "8.18.0",
     "picocolors": "1.1.1",

packages/appkit/src/core/agent/load-agents.ts

@@ -1,4 +1,5 @@
-import fs from "node:fs";
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
 import path from "node:path";
 import yaml from "js-yaml";
 import type { AgentAdapter } from "shared";
@@ -103,7 +104,7 @@ export async function loadAgentFromFile(
   filePath: string,
   ctx: LoadContext,
 ): Promise<AgentDefinition> {
-  const raw = fs.readFileSync(filePath, "utf-8");
+  const raw = await fs.readFile(filePath, "utf-8");
   const name = agentIdFromMarkdownPath(filePath);
   const { data } = parseFrontmatter(raw, filePath);
   if (Array.isArray(data?.agents) && data.agents.length > 0) {
@@ -138,11 +139,15 @@ export async function loadAgentsFromDir(
   dir: string,
   ctx: LoadContext,
 ): Promise<LoadResult> {
-  if (!fs.existsSync(dir)) {
-    return { defs: {}, defaultAgent: null };
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { defs: {}, defaultAgent: null };
+    }
+    throw err;
   }
-
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
   const orphanMd = entries
     .filter((e) => e.isFile() && e.name.endsWith(".md"))
     .map((e) => e.name)
@@ -174,12 +179,17 @@ export async function loadAgentsFromDir(
   // Pass 1: build every agent's definition; collect sub-agent refs.
   for (const id of agentIds) {
     const agentPath = path.join(dir, id, "agent.md");
-    if (!fs.existsSync(agentPath)) {
-      throw new Error(
-        `Agents subdirectory '${path.join(dir, id)}' must contain agent.md.`,
-      );
+    let raw: string;
+    try {
+      raw = await fs.readFile(agentPath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(
+          `Agents subdirectory '${path.join(dir, id)}' must contain agent.md.`,
+        );
+      }
+      throw err;
     }
-    const raw = fs.readFileSync(agentPath, "utf-8");
     defs[id] = buildDefinition(id, raw, agentPath, ctx);
     const { data } = parseFrontmatter(raw, agentPath);
     if (data?.agents !== undefined) {

packages/appkit/src/core/agent/run-agent.ts

@@ -5,6 +5,7 @@ import type {
   AgentToolDefinition,
   Message,
 } from "shared";
+import { consumeAdapterStream } from "./consume-adapter-stream";
 import {
   type FunctionTool,
   functionToolToDefinition,
@@ -78,7 +79,6 @@ export async function runAgent(
   };
 
   const events: AgentEvent[] = [];
-  let text = "";
 
   const stream = adapter.run(
     {
@@ -90,15 +90,15 @@ export async function runAgent(
     { executeTool, signal },
   );
 
-  for await (const event of stream) {
-    if (signal?.aborted) break;
-    events.push(event);
-    if (event.type === "message_delta") {
-      text += event.content;
-    } else if (event.type === "message") {
-      text = event.content;
-    }
-  }
+  // Shared accumulation rule (deltas append, `message` replaces). The
+  // `events` array is filled via the `onEvent` side effect so callers that
+  // inspect the raw stream still get the full record.
+  const text = await consumeAdapterStream(stream, {
+    signal,
+    onEvent: (event) => {
+      events.push(event);
+    },
+  });
 
   return { text, events };
 }