@northflare/runner 0.0.9 → 0.0.10

package/src/runner-sse.ts

@@ -18,137 +18,24 @@ import { EnhancedRepositoryManager } from "./components/enhanced-repository-mana
 import { StateManager } from "./utils/StateManager";
 import { createLogger } from "./utils/logger";
 import { statusLineManager } from "./utils/status-line";
+import { isRunnerDebugEnabled } from "./utils/debug";
 import fs from "fs/promises";
 import path from "path";
 import computerName from "computer-name";
+import {
+  sanitizeToolResponsePayload,
+  TOOL_RESPONSE_BYTE_LIMIT,
+} from "./utils/tool-response-sanitizer";
 
 const logger = createLogger("RunnerApp");
 
-const TOOL_RESPONSE_BYTE_LIMIT = 500 * 1024; // 500 KiB per tool response field
-const TOOL_RESPONSE_SUFFIX = "... [truncated]";
-
-function sanitizeToolResponsePayload(
-  method: string | undefined,
-  params: any
-): any {
-  if (method !== "message.agent" || !params) {
-    return params;
-  }
-
-  if (!isToolResultPayload(params)) {
-    return params;
-  }
-
-  const [sanitized, changed] = truncateStringsRecursively(params);
-  if (!changed) {
-    return params;
-  }
-
-  const toolUseId = extractToolUseId(params);
+function logToolResponseTruncation(toolUseId?: string) {
   const message = `Tool response exceeded ${TOOL_RESPONSE_BYTE_LIMIT} bytes and was truncated`;
   if (toolUseId) {
     logger.warn(message, { toolUseId });
   } else {
     logger.warn(message);
   }
-  return sanitized;
-}
-
-function isToolResultPayload(payload: any): boolean {
-  if (!payload) {
-    return false;
-  }
-  if (payload.type === "tool_result" || payload.subtype === "tool_result") {
-    return true;
-  }
-  if (Array.isArray(payload.content)) {
-    return payload.content.some((entry: any) => isToolResultBlock(entry));
-  }
-  return isToolResultBlock(payload.content);
-}
-
-function isToolResultBlock(block: any): boolean {
-  if (!block) {
-    return false;
-  }
-  return (
-    block.type === "tool_result" ||
-    block.subtype === "tool_result" ||
-    typeof block.tool_use_id === "string"
-  );
-}
-
-function extractToolUseId(payload: any): string | undefined {
-  if (!payload) {
-    return undefined;
-  }
-  if (typeof payload.tool_use_id === "string") {
-    return payload.tool_use_id;
-  }
-  if (Array.isArray(payload.content)) {
-    const match = payload.content.find(
-      (entry: any) => entry && typeof entry.tool_use_id === "string"
-    );
-    if (match) {
-      return match.tool_use_id;
-    }
-  }
-  if (payload.content && typeof payload.content === "object") {
-    return extractToolUseId(payload.content);
-  }
-  return undefined;
-}
-
-function truncateStringsRecursively(value: any): [any, boolean] {
-  if (typeof value === "string") {
-    return truncateStringValue(value);
-  }
-
-  if (Array.isArray(value)) {
-    let mutated = false;
-    let result: any[] = value;
-    for (let i = 0; i < value.length; i++) {
-      const [newItem, changed] = truncateStringsRecursively(value[i]);
-      if (changed) {
-        if (!mutated) {
-          result = value.slice();
-          mutated = true;
-        }
-        result[i] = newItem;
-      }
-    }
-    return [result, mutated];
-  }
-
-  if (value && typeof value === "object") {
-    let mutated = false;
-    let result: any = value;
-    for (const key of Object.keys(value)) {
-      const [newVal, changed] = truncateStringsRecursively(value[key]);
-      if (changed) {
-        if (!mutated) {
-          result = { ...value };
-          mutated = true;
-        }
-        result[key] = newVal;
-      }
-    }
-    return [result, mutated];
-  }
-
-  return [value, false];
-}
-
-function truncateStringValue(value: string): [string, boolean] {
-  const byteLength = Buffer.byteLength(value, "utf8");
-  if (byteLength <= TOOL_RESPONSE_BYTE_LIMIT) {
-    return [value, false];
-  }
-
-  const suffixBytes = Buffer.byteLength(TOOL_RESPONSE_SUFFIX, "utf8");
-  const maxBytes = Math.max(0, TOOL_RESPONSE_BYTE_LIMIT - suffixBytes);
-  const truncatedBuffer = Buffer.from(value, "utf8").subarray(0, maxBytes);
-  return [truncatedBuffer.toString("utf8") + TOOL_RESPONSE_SUFFIX, true];
 }
 
 export class RunnerApp implements IRunnerApp {
@@ -271,7 +158,7 @@ export class RunnerApp implements IRunnerApp {
       await this.registerWithRetry();
 
       // Log debug info after registration
-      if (process.env["DEBUG"] === "true") {
+      if (isRunnerDebugEnabled()) {
         logger.debug("Runner initialized with ownership details", {
           runnerId: this.config.runnerId,
           runnerUid: this.runnerUid,
@@ -325,7 +212,13 @@ export class RunnerApp implements IRunnerApp {
 
   async notify(method: string, params: any): Promise<void> {
     try {
-      const safeParams = sanitizeToolResponsePayload(method, params);
+      const sanitization = sanitizeToolResponsePayload(method, params);
+      if (sanitization.truncated) {
+        logToolResponseTruncation(sanitization.toolUseId);
+      }
+      const safeParams = sanitization.truncated
+        ? sanitization.params
+        : params;
       // Log RPC notification in debug mode
       logger.debug(`[RPC] Sending notification: ${method}`, {
         method,
@@ -357,17 +250,20 @@ export class RunnerApp implements IRunnerApp {
   }
 
   async sendToOrchestrator(message: JsonRpcMessage): Promise<any> {
-    const sanitizedParams = sanitizeToolResponsePayload(
+    const sanitization = sanitizeToolResponsePayload(
       message.method,
       message.params
     );
-    const messageToSend =
-      sanitizedParams === message.params
-        ? message
-        : {
-            ...message,
-            params: sanitizedParams,
-          };
+    if (sanitization.truncated) {
+      logToolResponseTruncation(sanitization.toolUseId);
+    }
+
+    const messageToSend = sanitization.truncated
+      ? {
+          ...message,
+          params: sanitization.params,
+        }
+      : message;
 
     try {
       // Log RPC request in debug mode
@@ -507,7 +403,7 @@ export class RunnerApp implements IRunnerApp {
       logger.info(`Registration response:`, JSON.stringify(response, null, 2));
 
       // Log the runnerRepos being sent and received
-      if (process.env["DEBUG"] === "true") {
+      if (isRunnerDebugEnabled()) {
         logger.debug(
           "Registration runnerRepos sent:",
           JSON.stringify(filteredRunnerRepos)
@@ -569,7 +465,7 @@ export class RunnerApp implements IRunnerApp {
         }
 
         // Debug logging for registration details
-        if (process.env["DEBUG"] === "true") {
+        if (isRunnerDebugEnabled()) {
           logger.debug("Registration complete with details", {
             runnerId: this.config.runnerId,
             runnerUid: this.runnerUid,
@@ -976,7 +872,7 @@ export class RunnerApp implements IRunnerApp {
       logger.error("Failed to persist active status:", error);
     });
 
-    if (process.env["DEBUG"] === "true") {
+    if (isRunnerDebugEnabled()) {
       logger.debug("Active runner status changed", {
         previous: previousState,
         new: active,
@@ -990,7 +886,7 @@ export class RunnerApp implements IRunnerApp {
     const previousTimestamp = this.lastProcessedAt;
     this.lastProcessedAt = timestamp;
 
-    if (process.env["DEBUG"] === "true") {
+    if (isRunnerDebugEnabled()) {
       logger.debug("LastProcessedAt updated", {
         previous: previousTimestamp?.toISOString() || "null",
         new: timestamp?.toISOString() || "null",

package/src/types/index.ts

@@ -59,5 +59,6 @@ export interface EnvironmentConfig {
   NORTHFLARE_RUNNER_TOKEN: string;
   NORTHFLARE_WORKSPACE_DIR: string;
   NORTHFLARE_ORCHESTRATOR_URL: string;
+  NORTHFLARE_RUNNER_DEBUG?: string;
   DEBUG?: string;
 }

package/src/utils/config.ts

@@ -294,6 +294,7 @@ export class ConfigManager {
       NORTHFLARE_RUNNER_TOKEN: process.env["NORTHFLARE_RUNNER_TOKEN"]!,
       NORTHFLARE_WORKSPACE_DIR: process.env["NORTHFLARE_WORKSPACE_DIR"]!,
       NORTHFLARE_ORCHESTRATOR_URL: process.env["NORTHFLARE_ORCHESTRATOR_URL"]!,
+      NORTHFLARE_RUNNER_DEBUG: process.env["NORTHFLARE_RUNNER_DEBUG"],
       DEBUG: process.env["DEBUG"],
     };
   }

package/src/utils/console.ts

@@ -2,7 +2,9 @@
  * Console wrapper that suppresses output when not in debug mode
  */
 
-const isDebug = process.env["DEBUG"] === "true";
+import { isRunnerDebugEnabled } from "./debug";
+
+const isDebug = isRunnerDebugEnabled();
 
 export const console = {
   log: isDebug ? global.console.log.bind(global.console) : () => {},
@@ -10,4 +12,4 @@ export const console = {
   error: global.console.error.bind(global.console), // Always show errors
   info: isDebug ? global.console.info.bind(global.console) : () => {},
   debug: isDebug ? global.console.debug.bind(global.console) : () => {},
-};
+};

package/src/utils/debug.ts

@@ -0,0 +1,18 @@
+export function isRunnerDebugEnabled(): boolean {
+  const explicitFlag = process.env["NORTHFLARE_RUNNER_DEBUG"];
+  if (typeof explicitFlag === "string") {
+    return isTruthy(explicitFlag);
+  }
+
+  const legacyFlag = process.env["DEBUG"];
+  if (typeof legacyFlag === "string") {
+    return isTruthy(legacyFlag);
+  }
+
+  return false;
+}
+
+function isTruthy(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
+}

package/src/utils/logger.ts

@@ -4,6 +4,7 @@
 
 import winston from "winston";
 import path from "path";
+import { isRunnerDebugEnabled } from "./debug";
 
 // Custom log levels
 const levels = {
@@ -29,6 +30,8 @@ const colors = {
 
 winston.addColors(colors);
 
+const debugEnabled = isRunnerDebugEnabled();
+
 // Format for console output
 const consoleFormat = winston.format.combine(
   winston.format.colorize({ all: true }),
@@ -36,7 +39,7 @@ const consoleFormat = winston.format.combine(
   winston.format.printf(({ timestamp, level, message, stack, ...metadata }) => {
     let msg = `${timestamp} [${level}]: ${message}`;
     // Only show stack traces and metadata in debug mode
-    if (process.env["DEBUG"] === "true") {
+    if (debugEnabled) {
       if (stack) {
         msg += `\n${stack}`;
       }
@@ -59,13 +62,13 @@ const fileFormat = winston.format.combine(
 
 // Create logger instance
 export const logger = winston.createLogger({
-  level: process.env["DEBUG"] === "true" ? "debug" : "info",
+  level: debugEnabled ? "debug" : "info",
   levels,
   transports: [
     // Always include console transport for errors
     new winston.transports.Console({
       format: consoleFormat,
-      level: process.env["DEBUG"] === "true" ? "debug" : "error",
+      level: debugEnabled ? "debug" : "error",
     }),
   ],
 });
@@ -94,7 +97,7 @@ export function configureFileLogging(logDir: string): void {
   );
 
   // Debug log file (only in debug mode)
-  if (process.env["DEBUG"] === "true") {
+  if (debugEnabled) {
     logger.add(
       new winston.transports.File({
         filename: path.join(logDir, "debug.log"),
@@ -128,4 +131,4 @@ logger.rejections.handle(
 );
 
 // Export default logger
-export default logger;
+export default logger;

package/src/utils/status-line.ts

@@ -1,11 +1,12 @@
 /**
  * StatusLineManager - Manages persistent status line output for active agent processes
- * 
+ *
  * This component maintains a single-line status output that updates every minute to show
  * the count of active agent processes. It prevents the machine from entering idle
  * state while processes are running and provides clear visual feedback without cluttering
  * the terminal with multiple log lines.
  */
+import { isRunnerDebugEnabled } from "./debug";
 
 export class StatusLineManager {
   private intervalId?: NodeJS.Timeout;
@@ -15,7 +16,7 @@ export class StatusLineManager {
 
   constructor() {
     // Only enable status line when not in debug mode
-    this.isEnabled = process.env["DEBUG"] !== "true";
+    this.isEnabled = !isRunnerDebugEnabled();
   }
 
   /**

package/src/utils/tool-response-sanitizer.ts

@@ -0,0 +1,160 @@
+export const TOOL_RESPONSE_BYTE_LIMIT = 500 * 1024; // 500 KiB cap per tool response payload
+export const TOOL_RESPONSE_SUFFIX = "... [truncated]";
+
+export interface ToolResponseSanitizationResult {
+  params: any;
+  truncated: boolean;
+  toolUseId?: string;
+}
+
+interface TruncationContext {
+  bytesRemaining: number;
+  truncated: boolean;
+}
+
+export function sanitizeToolResponsePayload(
+  method: string | undefined,
+  params: any
+): ToolResponseSanitizationResult {
+  if (method !== "message.agent" || !params) {
+    return { params, truncated: false };
+  }
+
+  if (!isToolResultPayload(params)) {
+    return { params, truncated: false };
+  }
+
+  const context: TruncationContext = {
+    bytesRemaining: TOOL_RESPONSE_BYTE_LIMIT,
+    truncated: false,
+  };
+
+  const [sanitized, changed] = truncateStringsRecursively(params, context);
+
+  if (!changed && !context.truncated) {
+    return { params, truncated: false };
+  }
+
+  return {
+    params: sanitized,
+    truncated: true,
+    toolUseId: extractToolUseId(params),
+  };
+}
+
+function isToolResultPayload(payload: any): boolean {
+  if (!payload) {
+    return false;
+  }
+  if (payload.type === "tool_result" || payload.subtype === "tool_result") {
+    return true;
+  }
+  if (Array.isArray(payload.content)) {
+    return payload.content.some((entry: any) => isToolResultBlock(entry));
+  }
+  return isToolResultBlock(payload.content);
+}
+
+function isToolResultBlock(block: any): boolean {
+  if (!block) {
+    return false;
+  }
+  return (
+    block.type === "tool_result" ||
+    block.subtype === "tool_result" ||
+    typeof block.tool_use_id === "string"
+  );
+}
+
+function extractToolUseId(payload: any): string | undefined {
+  if (!payload) {
+    return undefined;
+  }
+  if (typeof payload.tool_use_id === "string") {
+    return payload.tool_use_id;
+  }
+  if (Array.isArray(payload.content)) {
+    const match = payload.content.find(
+      (entry: any) => entry && typeof entry.tool_use_id === "string"
+    );
+    if (match) {
+      return match.tool_use_id;
+    }
+  }
+  if (payload.content && typeof payload.content === "object") {
+    return extractToolUseId(payload.content);
+  }
+  return undefined;
+}
+
+function truncateStringsRecursively(
+  value: any,
+  context: TruncationContext
+): [any, boolean] {
+  if (typeof value === "string") {
+    return truncateStringValue(value, context);
+  }
+
+  if (Array.isArray(value)) {
+    let mutated = false;
+    let result: any[] = value;
+    for (let i = 0; i < value.length; i++) {
+      const [newItem, changed] = truncateStringsRecursively(value[i], context);
+      if (changed) {
+        if (!mutated) {
+          result = value.slice();
+          mutated = true;
+        }
+        result[i] = newItem;
+      }
+    }
+    return [result, mutated];
+  }
+
+  if (value && typeof value === "object") {
+    let mutated = false;
+    let result: Record<string, any> = value;
+    for (const key of Object.keys(value)) {
+      const [newVal, changed] = truncateStringsRecursively(
+        value[key],
+        context
+      );
+      if (changed) {
+        if (!mutated) {
+          result = { ...value };
+          mutated = true;
+        }
+        result[key] = newVal;
+      }
+    }
+    return [result, mutated];
+  }
+
+  return [value, false];
+}
+
+function truncateStringValue(
+  value: string,
+  context: TruncationContext
+): [string, boolean] {
+  if (context.bytesRemaining <= 0) {
+    if (value.length === 0) {
+      return [value, false];
+    }
+    context.truncated = true;
+    return ["", true];
+  }
+
+  const byteLength = Buffer.byteLength(value, "utf8");
+  if (byteLength <= context.bytesRemaining) {
+    context.bytesRemaining -= byteLength;
+    return [value, false];
+  }
+
+  const suffixBytes = Buffer.byteLength(TOOL_RESPONSE_SUFFIX, "utf8");
+  const maxBytes = Math.max(0, context.bytesRemaining - suffixBytes);
+  const truncatedBuffer = Buffer.from(value, "utf8").subarray(0, maxBytes);
+  context.bytesRemaining = 0;
+  context.truncated = true;
+  return [truncatedBuffer.toString("utf8") + TOOL_RESPONSE_SUFFIX, true];
+}

package/tests/tool-response-sanitizer.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  sanitizeToolResponsePayload,
+  TOOL_RESPONSE_BYTE_LIMIT,
+  TOOL_RESPONSE_SUFFIX,
+} from "../src/utils/tool-response-sanitizer";
+
+describe("sanitizeToolResponsePayload", () => {
+  it("returns original params for non message.agent notifications", () => {
+    const payload = { type: "tool_result", content: [] };
+    const result = sanitizeToolResponsePayload("runner.heartbeat", payload);
+    expect(result.truncated).toBe(false);
+    expect(result.params).toBe(payload);
+  });
+
+  it("truncates oversized tool_result strings", () => {
+    const longText = "x".repeat(TOOL_RESPONSE_BYTE_LIMIT + 128);
+    const payload = {
+      type: "tool_result",
+      tool_use_id: "tool-123",
+      content: [{ type: "text", text: longText }],
+    };
+
+    const result = sanitizeToolResponsePayload("message.agent", payload);
+    expect(result.truncated).toBe(true);
+    expect(result.toolUseId).toBe("tool-123");
+
+    const sanitizedText = result.params.content[0].text as string;
+    expect(sanitizedText.endsWith(TOOL_RESPONSE_SUFFIX)).toBe(true);
+    expect(Buffer.byteLength(sanitizedText, "utf8")).toBeLessThanOrEqual(
+      TOOL_RESPONSE_BYTE_LIMIT + Buffer.byteLength(TOOL_RESPONSE_SUFFIX, "utf8")
+    );
+
+    // Ensure original payload was not mutated
+    expect(payload.content[0].text).toBe(longText);
+  });
+
+  it("enforces the byte budget across multiple string blocks", () => {
+    const firstBlockBytes = 400 * 1024;
+    const secondBlockBytes = 200 * 1024;
+    const payload = {
+      type: "tool_result",
+      content: [
+        { type: "text", text: "a".repeat(firstBlockBytes) },
+        { type: "text", text: "b".repeat(secondBlockBytes) },
+      ],
+    };
+
+    const result = sanitizeToolResponsePayload("message.agent", payload);
+    expect(result.truncated).toBe(true);
+
+    const first = result.params.content[0].text as string;
+    const second = result.params.content[1].text as string;
+
+    expect(Buffer.byteLength(first, "utf8")).toBe(firstBlockBytes);
+    expect(second.endsWith(TOOL_RESPONSE_SUFFIX)).toBe(true);
+    const combinedBytes =
+      Buffer.byteLength(first, "utf8") + Buffer.byteLength(second, "utf8");
+    expect(combinedBytes).toBeLessThanOrEqual(
+      TOOL_RESPONSE_BYTE_LIMIT + Buffer.byteLength(TOOL_RESPONSE_SUFFIX, "utf8")
+    );
+  });
+});