@dexto/tools-lifecycle 1.6.0

package/dist/view-logs-tool.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { Tool } from '@dexto/core';
+
+declare const ViewLogsInputSchema: z.ZodObject<{
+    lines: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    query: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["debug", "info", "warn", "error", "silly"]>, z.ZodArray<z.ZodEnum<["debug", "info", "warn", "error", "silly"]>, "many">]>>;
+    component: z.ZodOptional<z.ZodString>;
+    includeContext: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strict", z.ZodTypeAny, {
+    lines: number;
+    includeContext: boolean;
+    query?: string | undefined;
+    level?: "debug" | "info" | "warn" | "error" | "silly" | ("debug" | "info" | "warn" | "error" | "silly")[] | undefined;
+    component?: string | undefined;
+}, {
+    lines?: number | undefined;
+    query?: string | undefined;
+    level?: "debug" | "info" | "warn" | "error" | "silly" | ("debug" | "info" | "warn" | "error" | "silly")[] | undefined;
+    component?: string | undefined;
+    includeContext?: boolean | undefined;
+}>;
+declare function createViewLogsTool(options: {
+    maxLogLines: number;
+    maxLogBytes: number;
+}): Tool<typeof ViewLogsInputSchema>;
+
+export { createViewLogsTool };

package/dist/view-logs-tool.js

@@ -0,0 +1,149 @@
+import * as fs from "node:fs/promises";
+import { z } from "zod";
+import { ToolError, defineTool } from "@dexto/core";
+const LOG_LEVEL_VALUES = ["debug", "info", "warn", "error", "silly"];
+const ViewLogsInputSchema = z.object({
+  lines: z.number().int().positive().optional().default(200).describe("Number of log lines to return from the end of the log file"),
+  query: z.string().optional().describe("Optional: filter logs by substring match (case-insensitive)"),
+  level: z.union([z.enum(LOG_LEVEL_VALUES), z.array(z.enum(LOG_LEVEL_VALUES))]).optional().describe("Optional: filter logs by level"),
+  component: z.string().optional().describe("Optional: filter logs by component"),
+  includeContext: z.boolean().optional().default(false).describe("Whether to include structured context for JSON log entries")
+}).strict();
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tryParseLogEntry(line) {
+  try {
+    const parsed = JSON.parse(line);
+    if (!isPlainObject(parsed)) {
+      return null;
+    }
+    const level = parsed.level;
+    const message = parsed.message;
+    const timestamp = parsed.timestamp;
+    const component = parsed.component;
+    if (typeof level !== "string" || !LOG_LEVEL_VALUES.includes(level) || typeof message !== "string" || typeof timestamp !== "string" || typeof component !== "string") {
+      return null;
+    }
+    const agentId = parsed.agentId;
+    const sessionId = parsed.sessionId;
+    const toolCallId = parsed.toolCallId;
+    const context = parsed.context;
+    return {
+      level,
+      message,
+      timestamp,
+      component,
+      ...typeof agentId === "string" && { agentId },
+      ...typeof sessionId === "string" && { sessionId },
+      ...typeof toolCallId === "string" && { toolCallId },
+      ...isPlainObject(context) && { context }
+    };
+  } catch {
+    return null;
+  }
+}
+async function readTailBytes(filePath, maxBytes) {
+  const handle = await fs.open(filePath, "r");
+  try {
+    const stat = await handle.stat();
+    const start = Math.max(0, stat.size - maxBytes);
+    const length = stat.size - start;
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+function createViewLogsTool(options) {
+  return defineTool({
+    id: "view_logs",
+    displayName: "View Logs",
+    description: "View this session log file (tail). Returns the most recent log lines for debugging. If file logging is not configured, returns a message instead.",
+    inputSchema: ViewLogsInputSchema,
+    async execute(parsed, context) {
+      const logFilePath = context.logger.getLogFilePath();
+      if (!logFilePath) {
+        return {
+          logFilePath: null,
+          lines: 0,
+          content: "",
+          message: "No log file is configured for this session."
+        };
+      }
+      const requestedLines = parsed.lines;
+      const maxLines = options.maxLogLines;
+      const linesToReturn = Math.min(requestedLines, maxLines);
+      const query = parsed.query?.trim();
+      const queryLower = query ? query.toLowerCase() : null;
+      const component = parsed.component?.trim();
+      const levelsInput = parsed.level;
+      const levels = typeof levelsInput === "string" ? /* @__PURE__ */ new Set([levelsInput]) : Array.isArray(levelsInput) ? new Set(levelsInput) : null;
+      let tailContent;
+      try {
+        tailContent = await readTailBytes(logFilePath, options.maxLogBytes);
+      } catch (error) {
+        throw ToolError.executionFailed(
+          "view_logs",
+          `Failed to read log file: ${error instanceof Error ? error.message : String(error)}`,
+          context.sessionId
+        );
+      }
+      const allLines = tailContent.split(/\r?\n/).map((l) => l.trimEnd()).filter((l) => l.trim().length > 0);
+      const candidates = allLines.map((line) => ({
+        raw: line,
+        entry: tryParseLogEntry(line)
+      }));
+      const filtered = candidates.filter(({ raw, entry }) => {
+        if (entry) {
+          if (levels && !levels.has(entry.level)) {
+            return false;
+          }
+          if (component && entry.component !== component) {
+            return false;
+          }
+          if (!queryLower) {
+            return true;
+          }
+          const contextText = entry.context ? JSON.stringify(entry.context) : "";
+          return entry.message.toLowerCase().includes(queryLower) || contextText.toLowerCase().includes(queryLower);
+        }
+        if (levels || component) {
+          return false;
+        }
+        if (!queryLower) {
+          return true;
+        }
+        return raw.toLowerCase().includes(queryLower);
+      });
+      const limited = filtered.slice(Math.max(0, filtered.length - linesToReturn));
+      const outputLines = limited.map((l) => l.raw);
+      const entries = limited.map(({ entry }) => entry).filter((entry) => entry !== null).map(
+        (entry) => parsed.includeContext ? entry : {
+          level: entry.level,
+          message: entry.message,
+          timestamp: entry.timestamp,
+          component: entry.component,
+          ...entry.agentId !== void 0 && { agentId: entry.agentId },
+          ...entry.sessionId !== void 0 && { sessionId: entry.sessionId },
+          ...entry.toolCallId !== void 0 && {
+            toolCallId: entry.toolCallId
+          }
+        }
+      );
+      return {
+        logFilePath,
+        lines: outputLines.length,
+        content: outputLines.join("\n"),
+        ...entries.length > 0 && { entries },
+        ...query !== void 0 && query.length > 0 && { query },
+        ...levelsInput !== void 0 && { level: levelsInput },
+        ...component !== void 0 && component.length > 0 && { component }
+      };
+    }
+  });
+}
+export {
+  createViewLogsTool
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dexto/tools-lifecycle",
+  "version": "1.6.0",
+  "description": "Lifecycle and self-observation tools for Dexto agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "dexto",
+    "tools",
+    "lifecycle",
+    "logs",
+    "memories"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0",
+    "@dexto/agent-config": "1.6.0",
+    "@dexto/core": "1.6.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}