@personaai/runtime 0.5.2 → 0.5.3

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ChatMessageInput } from '@personaai/sdk';
+import { ChatMessageInput, LogLevel, Logger } from '@personaai/sdk';
 
 type RuntimeMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /** A single uploaded file — present on `RuntimeRequest.file` for a multipart `POST /files`. */
@@ -220,6 +220,10 @@ interface CreateRuntimeOptions {
     maxTrackedRuns?: number;
     /** Opt-in switches for Project-level admin surface. See {@link RuntimeCapabilities} — everything defaults to off. */
     capabilities?: RuntimeCapabilities;
+    /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
+    logLevel?: LogLevel;
+    /** Custom logger instance — when provided, `logLevel` is ignored. */
+    logger?: Logger;
 }
 interface Runtime {
     handle(request: RuntimeRequest): Promise<RuntimeResponse>;
@@ -242,6 +246,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.5.2";
+declare const RUNTIME_VERSION = "0.5.3";
 
 export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type ResolveUser, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, createRuntime };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ChatMessageInput } from '@personaai/sdk';
+import { ChatMessageInput, LogLevel, Logger } from '@personaai/sdk';
 
 type RuntimeMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /** A single uploaded file — present on `RuntimeRequest.file` for a multipart `POST /files`. */
@@ -220,6 +220,10 @@ interface CreateRuntimeOptions {
     maxTrackedRuns?: number;
     /** Opt-in switches for Project-level admin surface. See {@link RuntimeCapabilities} — everything defaults to off. */
     capabilities?: RuntimeCapabilities;
+    /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
+    logLevel?: LogLevel;
+    /** Custom logger instance — when provided, `logLevel` is ignored. */
+    logger?: Logger;
 }
 interface Runtime {
     handle(request: RuntimeRequest): Promise<RuntimeResponse>;
@@ -242,6 +246,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.5.2";
+declare const RUNTIME_VERSION = "0.5.3";
 
 export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type ResolveUser, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, createRuntime };

package/dist/index.js

@@ -41,12 +41,14 @@ function stripMountPath(path, mountPath) {
 
 // src/client-factory.ts
 import { PersonaClient } from "@personaai/sdk";
-function createClientForRequest(options, userId) {
+function createClientForRequest(options, userId, logger) {
+  const clientLogger = logger ? logger.child("sdk") : void 0;
   return new PersonaClient({
     baseUrl: options.baseUrl,
     credential: options.credential,
     externalUserId: userId ?? void 0,
-    fetch: options.fetch
+    fetch: options.fetch,
+    logger: clientLogger
   });
 }
 
@@ -105,6 +107,9 @@ function errorToResponse(err, mode) {
   };
 }
 
+// src/runtime.ts
+import { createLogger } from "@personaai/sdk";
+
 // src/runRegistry.ts
 var DEFAULT_RUN_GRACE_MS = 5 * 60 * 1e3;
 var DEFAULT_MAX_TRACKED_RUNS = 1e3;
@@ -126,7 +131,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 = {
@@ -448,7 +453,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,
@@ -457,7 +471,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,
@@ -465,9 +482,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,
@@ -500,22 +536,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,
@@ -1348,23 +1406,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 ?? 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",
@@ -1372,49 +1493,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 });
     }
   };
 }