@personaai/runtime 0.5.2 → 0.5.3

package/README.md

@@ -407,10 +407,10 @@ genuine unclosed gap or an intentional package boundary, not an oversight:
 - **Fine-grained (per-user, per-action) permissions within an enabled capability** — **by
   design**, not a gap: see [Capabilities](#capabilities--admin-surface). A capability is on or off
   per mount; anything finer belongs in `resolveUser` or a hook, not the runtime.
-- Framework adapters beyond Express (`@personaai/nextjs`, `@personaai/node`, `@personaai/fastify`,
-  `@personaai/hono`, `@personaai/nestjs`) — **by design**, not a gap: this package is the
-  foundation they're meant to wrap, not a replacement for them. `@personaai/express` (Wave 3)
-  has shipped as the first.
+- Framework adapters beyond the shipped ones (`@personaai/node`, `@personaai/fastify`,
+  `@personaai/hono`) — **by design**, not a gap: this package is the foundation they're meant to
+  wrap, not a replacement for them. `@personaai/nextjs` (Wave 2), `@personaai/express` and
+  `@personaai/nestjs` (Wave 3) have shipped.
 
 ## Roadmap
 

package/dist/index.cjs

@@ -69,12 +69,14 @@ function stripMountPath(path, mountPath) {
 
 // src/client-factory.ts
 var import_sdk = require("@personaai/sdk");
-function createClientForRequest(options, userId) {
+function createClientForRequest(options, userId, logger) {
+  const clientLogger = logger ? logger.child("sdk") : void 0;
   return new import_sdk.PersonaClient({
     baseUrl: options.baseUrl,
     credential: options.credential,
     externalUserId: userId ?? void 0,
-    fetch: options.fetch
+    fetch: options.fetch,
+    logger: clientLogger
   });
 }
 
@@ -133,6 +135,9 @@ function errorToResponse(err, mode) {
   };
 }
 
+// src/runtime.ts
+var import_sdk4 = require("@personaai/sdk");
+
 // src/runRegistry.ts
 var DEFAULT_RUN_GRACE_MS = 5 * 60 * 1e3;
 var DEFAULT_MAX_TRACKED_RUNS = 1e3;
@@ -154,7 +159,7 @@ function evictStaleRuns(runs, now, graceMs = DEFAULT_RUN_GRACE_MS, maxTracked =
 }
 
 // src/version.ts
-var RUNTIME_VERSION = "0.5.2";
+var RUNTIME_VERSION = "0.5.3";
 
 // src/routes/health.ts
 var alwaysOnCapabilities = {
@@ -476,7 +481,16 @@ function parseChatBody(body) {
   };
 }
 var chatRoute = async (request, ctx) => {
+  const logger = ctx.logger.child("chat");
+  logger.debug("chatRoute start", { userId: request.userId, hasBody: !!request.body });
   const body = parseChatBody(request.body);
+  logger.trace("chatRoute body", {
+    agentId: body.agentId,
+    threadId: body.threadId,
+    messageCount: body.messages?.length ?? 0,
+    hasResume: !!body.resume,
+    hasContextOverride: !!body.contextOverride
+  });
   const userId = request.userId;
   const runCtx = {
     userId,
@@ -485,7 +499,10 @@ var chatRoute = async (request, ctx) => {
     threadId: body.threadId,
     messages: body.messages
   };
+  logger.debug("beforeRun hook", { agentId: body.agentId, threadId: body.threadId });
   await ctx.hooks?.beforeRun?.(runCtx);
+  logger.trace("beforeRun completed", { agentId: body.agentId });
+  logger.debug("starting chat stream", { agentId: body.agentId, threadId: body.threadId });
   const stream = ctx.client.chat.stream(body.agentId, {
     messages: body.messages,
     threadId: body.threadId,
@@ -493,9 +510,28 @@ var chatRoute = async (request, ctx) => {
     contextOverride: body.contextOverride
   });
   const runId = crypto.randomUUID();
+  logger.info("chat run created", {
+    runId,
+    agentId: body.agentId,
+    threadId: body.threadId,
+    userId
+  });
   const driver = new RunDriver(runId, runCtx, stream, ctx.hooks, ctx.mode);
   ctx.runs.set(runId, driver);
-  await driver.waitForFirstFrame();
+  logger.debug("run driver registered", { runId, trackedRuns: ctx.runs.size });
+  try {
+    await driver.waitForFirstFrame();
+    logger.debug("chat run first frame ready", { runId });
+  } catch (err) {
+    logger.warn("chat run failed before first frame", {
+      runId,
+      agentId: body.agentId,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    ctx.runs.delete(runId);
+    throw err;
+  }
+  logger.info("chat stream ready", { runId, agentId: body.agentId });
   return {
     kind: "stream",
     status: 200,
@@ -528,22 +564,44 @@ function parseArchitectBody(body) {
   };
 }
 var architectRoute = async (request, ctx) => {
+  const logger = ctx.logger.child("architect");
+  logger.debug("architectRoute start", { userId: request.userId });
   const body = parseArchitectBody(request.body);
+  logger.trace("architectRoute body", {
+    messageCount: body.messages?.length ?? 0,
+    hasResume: !!body.resume
+  });
   const userId = request.userId;
   const runCtx = {
     userId,
     kind: "architect",
     messages: body.messages
   };
+  logger.debug("beforeRun hook (architect)", { userId });
   await ctx.hooks?.beforeRun?.(runCtx);
+  logger.trace("beforeRun completed (architect)");
+  logger.debug("starting architect stream");
   const stream = ctx.client.architect.stream({
     messages: body.messages,
     resume: body.resume
   });
   const runId = crypto.randomUUID();
+  logger.info("architect run created", { runId, userId });
   const driver = new RunDriver(runId, runCtx, stream, ctx.hooks, ctx.mode);
   ctx.runs.set(runId, driver);
-  await driver.waitForFirstFrame();
+  logger.debug("architect driver registered", { runId, trackedRuns: ctx.runs.size });
+  try {
+    await driver.waitForFirstFrame();
+    logger.debug("architect first frame ready", { runId });
+  } catch (err) {
+    logger.warn("architect run failed before first frame", {
+      runId,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    ctx.runs.delete(runId);
+    throw err;
+  }
+  logger.info("architect stream ready", { runId });
   return {
     kind: "stream",
     status: 200,
@@ -1376,23 +1434,86 @@ function createRuntime(options) {
   if (!options.baseUrl) throw new Error('createRuntime: "baseUrl" is required');
   if (!options.credential) throw new Error('createRuntime: "credential" is required');
   if (!options.resolveUser) throw new Error('createRuntime: "resolveUser" is required');
+  const logger = options.logger ?? (0, import_sdk4.createLogger)(
+    "runtime",
+    options.logLevel !== void 0 ? { level: options.logLevel } : void 0
+  );
   const capabilities = resolveCapabilities(options.capabilities);
   const routes = buildRoutes(capabilities);
   const mode = resolveMode(options);
   const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15e3;
   const runGraceMs = options.runGraceMs ?? DEFAULT_RUN_GRACE_MS;
   const maxTrackedRuns = options.maxTrackedRuns ?? DEFAULT_MAX_TRACKED_RUNS;
+  logger.debug("runtime init", {
+    mode,
+    mountPath: options.mountPath ?? "",
+    capabilities,
+    heartbeatIntervalMs,
+    runGraceMs,
+    maxTrackedRuns
+  });
+  const enabledCaps = Object.entries(capabilities).filter(([, v]) => v).map(([k]) => k);
+  logger.info("runtime created", {
+    mode,
+    mountPath: options.mountPath ?? "",
+    enabledCapabilities: enabledCaps.length ? enabledCaps : ["(core only)"]
+  });
+  logger.trace("runtime config", {
+    baseUrl: options.baseUrl,
+    hasHooks: !!options.hooks,
+    routeCount: routes.length
+  });
   const runs = /* @__PURE__ */ new Map();
-  const evictionTimer = setInterval(
-    () => evictStaleRuns(runs, Date.now(), runGraceMs, maxTrackedRuns),
-    6e4
-  );
+  const evictionTimer = setInterval(() => {
+    const before = runs.size;
+    evictStaleRuns(runs, Date.now(), runGraceMs, maxTrackedRuns);
+    if (runs.size !== before) {
+      logger.debug("run eviction sweep", { before, after: runs.size, runGraceMs, maxTrackedRuns });
+    } else {
+      logger.trace("run eviction sweep \u2014 no evictions", { before });
+    }
+  }, 6e4);
   evictionTimer.unref?.();
+  function getRequestPreview(req) {
+    const preview = {
+      method: req.method,
+      path: req.path,
+      hasQuery: req.query && Object.keys(req.query).length > 0,
+      hasBody: req.body !== void 0,
+      hasFile: !!req.file,
+      fileCount: req.files?.length ?? 0,
+      userId: req.userId ?? null
+    };
+    if (req.headers) {
+      const redacted = {};
+      for (const [k, v] of Object.entries(req.headers)) {
+        if (v === void 0) continue;
+        if (k.toLowerCase() === "authorization") redacted[k] = "***";
+        else redacted[k] = v;
+      }
+      preview.headers = redacted;
+    }
+    if (req.query && Object.keys(req.query).length) preview.query = req.query;
+    return preview;
+  }
   async function handle(request) {
+    const startMs = Date.now();
+    logger.debug("handle start", { method: request.method, path: request.path });
+    logger.trace("handle request details", getRequestPreview(request));
     try {
       const path = stripMountPath(request.path, options.mountPath);
+      logger.trace("stripMountPath", {
+        originalPath: request.path,
+        mountPath: options.mountPath ?? "",
+        strippedPath: path
+      });
       const match = matchRoute(routes, request.method, path);
       if (match.kind === "not-found") {
+        logger.warn("route not found", {
+          method: request.method,
+          path: request.path,
+          strippedPath: path
+        });
         throw new RuntimeHttpError(
           404,
           "NOT_FOUND",
@@ -1400,49 +1521,144 @@ function createRuntime(options) {
         );
       }
       if (match.kind === "method-not-allowed") {
+        logger.warn("method not allowed", {
+          method: request.method,
+          path: request.path,
+          strippedPath: path,
+          allowed: match.allowed
+        });
         const err = new RuntimeHttpError(
           405,
           "METHOD_NOT_ALLOWED",
           `${request.method} not allowed on ${request.path}. Allowed: ${match.allowed.join(", ")}.`
         );
-        const response = errorToResponse(err, mode);
-        return { ...response, headers: { ...response.headers, Allow: match.allowed.join(", ") } };
+        const response2 = errorToResponse(err, mode);
+        logger.debug("handle completed \u2014 405", {
+          method: request.method,
+          path: request.path,
+          allowed: match.allowed,
+          durationMs: Date.now() - startMs
+        });
+        return { ...response2, headers: { ...response2.headers, Allow: match.allowed.join(", ") } };
       }
+      logger.info("route matched", {
+        method: request.method,
+        path: request.path,
+        strippedPath: path,
+        pattern: match.route.pattern.join("/"),
+        params: match.params,
+        requiresAuth: match.route.requiresAuth !== false
+      });
+      logger.debug("route matched", {
+        method: request.method,
+        path,
+        pattern: match.route.pattern,
+        params: match.params
+      });
+      logger.trace("route handler", {
+        handler: match.route.handler.name || "anonymous",
+        pattern: match.route.pattern
+      });
       let userId = null;
       if (match.route.requiresAuth !== false) {
+        logger.debug("resolving user", { path: request.path });
         try {
           const resolved = await options.resolveUser(request);
           userId = typeof resolved === "string" && resolved.length > 0 ? resolved : null;
-        } catch {
+          logger.trace("resolveUser result", { userId: userId ?? null, hasResult: !!userId });
+        } catch (err) {
           userId = null;
+          logger.warn("resolveUser threw", {
+            path: request.path,
+            error: err instanceof Error ? err.message : String(err)
+          });
         }
         if (userId === null) {
+          logger.warn("unauthorized \u2014 could not resolve user", {
+            method: request.method,
+            path: request.path
+          });
           throw new RuntimeHttpError(
             401,
             "UNAUTHORIZED",
             "Could not resolve an authenticated user for this request."
           );
         }
+        logger.debug("user resolved", { userId });
+      } else {
+        logger.debug("skipping auth for public route", { path: request.path });
       }
       const resolvedRequest = { ...request, userId };
-      const client = createClientForRequest(options, userId);
-      return await match.route.handler(resolvedRequest, {
+      const client = createClientForRequest(options, userId, logger);
+      const routeLogger = logger.child("route");
+      logger.debug("handler start", {
+        method: request.method,
+        path: request.path,
+        handler: match.route.handler.name || "anonymous",
+        userId
+      });
+      const response = await match.route.handler(resolvedRequest, {
         client,
         hooks: options.hooks,
         mode,
         params: match.params,
         heartbeatIntervalMs,
         runs,
-        capabilities
+        capabilities,
+        logger: routeLogger
       });
+      const durationMs = Date.now() - startMs;
+      logger.info("handle succeeded", {
+        method: request.method,
+        path: request.path,
+        status: response.status,
+        kind: response.kind,
+        durationMs,
+        userId
+      });
+      logger.debug("handle completed", {
+        method: request.method,
+        path: request.path,
+        status: response.status,
+        durationMs
+      });
+      logger.trace("handle response details", {
+        method: request.method,
+        path: request.path,
+        status: response.status,
+        headers: response.headers,
+        kind: response.kind,
+        durationMs
+      });
+      return response;
     } catch (err) {
+      const durationMs = Date.now() - startMs;
+      const isHttpError = err instanceof RuntimeHttpError;
+      const meta = {
+        method: request.method,
+        path: request.path,
+        durationMs,
+        error: err instanceof Error ? err.message : String(err),
+        code: isHttpError ? err.code : void 0,
+        status: isHttpError ? err.status : void 0
+      };
+      if (isHttpError && err.status >= 500) {
+        logger.error("handle failed \u2014 server error", meta);
+      } else if (isHttpError && err.status >= 400) {
+        logger.warn("handle failed \u2014 client error", meta);
+      } else {
+        logger.error("handle failed \u2014 unexpected error", meta);
+      }
+      logger.trace("handle error details", { error: err, durationMs });
       return errorToResponse(err, mode);
     }
   }
   return {
     handle,
     close() {
+      logger.debug("runtime close", { trackedRuns: runs.size });
       clearInterval(evictionTimer);
+      logger.info("runtime closed", { trackedRuns: runs.size });
     }
   };
 }