@dexto/tools-lifecycle 1.6.0

package/dist/search-history-tool.cjs

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var search_history_tool_exports = {};
+__export(search_history_tool_exports, {
+  createSearchHistoryTool: () => createSearchHistoryTool
+});
+module.exports = __toCommonJS(search_history_tool_exports);
+var import_zod = require("zod");
+var import_core = require("@dexto/core");
+const SearchHistoryInputSchema = import_zod.z.object({
+  query: import_zod.z.string().describe("The search query to find in conversation history"),
+  mode: import_zod.z.enum(["messages", "sessions"]).describe(
+    'Search mode: "messages" searches for individual messages, "sessions" finds sessions containing the query'
+  ),
+  sessionId: import_zod.z.string().optional().describe('Optional: limit search to a specific session (only for mode="messages")'),
+  role: import_zod.z.enum(["user", "assistant", "system", "tool"]).optional().describe('Optional: filter by message role (only for mode="messages")'),
+  limit: import_zod.z.number().optional().default(20).describe(
+    'Optional: maximum number of results to return (default: 20, only for mode="messages")'
+  ),
+  offset: import_zod.z.number().optional().default(0).describe('Optional: offset for pagination (default: 0, only for mode="messages")')
+}).strict();
+function createSearchHistoryTool() {
+  return (0, import_core.defineTool)({
+    id: "search_history",
+    displayName: "Search History",
+    description: 'Search through conversation history across sessions. Use mode="messages" to search for specific messages, or mode="sessions" to find sessions containing the query. For message search, you can filter by sessionId (specific session), role (user/assistant/system/tool), limit results, and set pagination offset.',
+    inputSchema: SearchHistoryInputSchema,
+    async execute(input, context) {
+      const { query, mode, sessionId, role, limit, offset } = input;
+      const searchService = context.services?.search;
+      if (!searchService) {
+        throw import_core.ToolError.configInvalid(
+          "search_history requires ToolExecutionContext.services.search"
+        );
+      }
+      if (mode === "messages") {
+        const searchOptions = {
+          limit,
+          offset,
+          ...sessionId !== void 0 && { sessionId },
+          ...role !== void 0 && { role }
+        };
+        return await searchService.searchMessages(query, searchOptions);
+      }
+      return await searchService.searchSessions(query);
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSearchHistoryTool
+});

package/dist/search-history-tool.d.cts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { Tool } from '@dexto/core';
+
+declare const SearchHistoryInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodEnum<["messages", "sessions"]>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<["user", "assistant", "system", "tool"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strict", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+    offset: number;
+    mode: "messages" | "sessions";
+    sessionId?: string | undefined;
+    role?: "user" | "system" | "assistant" | "tool" | undefined;
+}, {
+    query: string;
+    mode: "messages" | "sessions";
+    sessionId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    role?: "user" | "system" | "assistant" | "tool" | undefined;
+}>;
+/**
+ * Create the `search_history` tool.
+ *
+ * Searches message/session history using the configured SearchService.
+ * Requires `ToolExecutionContext.services.search`.
+ */
+declare function createSearchHistoryTool(): Tool<typeof SearchHistoryInputSchema>;
+
+export { createSearchHistoryTool };

package/dist/search-history-tool.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { Tool } from '@dexto/core';
+
+declare const SearchHistoryInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodEnum<["messages", "sessions"]>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<["user", "assistant", "system", "tool"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strict", z.ZodTypeAny, {
+    query: string;
+    limit: number;
+    offset: number;
+    mode: "messages" | "sessions";
+    sessionId?: string | undefined;
+    role?: "user" | "system" | "assistant" | "tool" | undefined;
+}, {
+    query: string;
+    mode: "messages" | "sessions";
+    sessionId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    role?: "user" | "system" | "assistant" | "tool" | undefined;
+}>;
+/**
+ * Create the `search_history` tool.
+ *
+ * Searches message/session history using the configured SearchService.
+ * Requires `ToolExecutionContext.services.search`.
+ */
+declare function createSearchHistoryTool(): Tool<typeof SearchHistoryInputSchema>;
+
+export { createSearchHistoryTool };

package/dist/search-history-tool.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ToolError, defineTool } from "@dexto/core";
+const SearchHistoryInputSchema = z.object({
+  query: z.string().describe("The search query to find in conversation history"),
+  mode: z.enum(["messages", "sessions"]).describe(
+    'Search mode: "messages" searches for individual messages, "sessions" finds sessions containing the query'
+  ),
+  sessionId: z.string().optional().describe('Optional: limit search to a specific session (only for mode="messages")'),
+  role: z.enum(["user", "assistant", "system", "tool"]).optional().describe('Optional: filter by message role (only for mode="messages")'),
+  limit: z.number().optional().default(20).describe(
+    'Optional: maximum number of results to return (default: 20, only for mode="messages")'
+  ),
+  offset: z.number().optional().default(0).describe('Optional: offset for pagination (default: 0, only for mode="messages")')
+}).strict();
+function createSearchHistoryTool() {
+  return defineTool({
+    id: "search_history",
+    displayName: "Search History",
+    description: 'Search through conversation history across sessions. Use mode="messages" to search for specific messages, or mode="sessions" to find sessions containing the query. For message search, you can filter by sessionId (specific session), role (user/assistant/system/tool), limit results, and set pagination offset.',
+    inputSchema: SearchHistoryInputSchema,
+    async execute(input, context) {
+      const { query, mode, sessionId, role, limit, offset } = input;
+      const searchService = context.services?.search;
+      if (!searchService) {
+        throw ToolError.configInvalid(
+          "search_history requires ToolExecutionContext.services.search"
+        );
+      }
+      if (mode === "messages") {
+        const searchOptions = {
+          limit,
+          offset,
+          ...sessionId !== void 0 && { sessionId },
+          ...role !== void 0 && { role }
+        };
+        return await searchService.searchMessages(query, searchOptions);
+      }
+      return await searchService.searchSessions(query);
+    }
+  });
+}
+export {
+  createSearchHistoryTool
+};

package/dist/tool-factory-config.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_factory_config_exports = {};
+__export(tool_factory_config_exports, {
+  LIFECYCLE_TOOL_NAMES: () => LIFECYCLE_TOOL_NAMES,
+  LifecycleToolsConfigSchema: () => LifecycleToolsConfigSchema
+});
+module.exports = __toCommonJS(tool_factory_config_exports);
+var import_zod = require("zod");
+const DEFAULT_MAX_LOG_LINES = 200;
+const DEFAULT_MAX_LOG_BYTES = 2e5;
+const LIFECYCLE_TOOL_NAMES = [
+  "view_logs",
+  "search_history",
+  "memory_list",
+  "memory_get",
+  "memory_create",
+  "memory_update",
+  "memory_delete"
+];
+const LifecycleToolsConfigSchema = import_zod.z.object({
+  type: import_zod.z.literal("lifecycle-tools"),
+  enabledTools: import_zod.z.array(import_zod.z.enum(LIFECYCLE_TOOL_NAMES)).optional().describe(
+    `Subset of tools to enable. If not specified, all tools are enabled. Available: ${LIFECYCLE_TOOL_NAMES.join(", ")}`
+  ),
+  maxLogLines: import_zod.z.number().int().positive().default(DEFAULT_MAX_LOG_LINES).describe(
+    `Maximum number of log lines view_logs may return (default: ${DEFAULT_MAX_LOG_LINES})`
+  ),
+  maxLogBytes: import_zod.z.number().int().positive().default(DEFAULT_MAX_LOG_BYTES).describe(
+    `Maximum bytes read from the end of the log file (default: ${DEFAULT_MAX_LOG_BYTES})`
+  )
+}).strict();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LIFECYCLE_TOOL_NAMES,
+  LifecycleToolsConfigSchema
+});

package/dist/tool-factory-config.d.cts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+declare const LIFECYCLE_TOOL_NAMES: readonly ["view_logs", "search_history", "memory_list", "memory_get", "memory_create", "memory_update", "memory_delete"];
+type LifecycleToolName = (typeof LIFECYCLE_TOOL_NAMES)[number];
+declare const LifecycleToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lifecycle-tools">;
+    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["view_logs", "search_history", "memory_list", "memory_get", "memory_create", "memory_update", "memory_delete"]>, "many">>;
+    maxLogLines: z.ZodDefault<z.ZodNumber>;
+    maxLogBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "lifecycle-tools";
+    maxLogLines: number;
+    maxLogBytes: number;
+    enabledTools?: ("view_logs" | "search_history" | "memory_list" | "memory_get" | "memory_create" | "memory_update" | "memory_delete")[] | undefined;
+}, {
+    type: "lifecycle-tools";
+    enabledTools?: ("view_logs" | "search_history" | "memory_list" | "memory_get" | "memory_create" | "memory_update" | "memory_delete")[] | undefined;
+    maxLogLines?: number | undefined;
+    maxLogBytes?: number | undefined;
+}>;
+type LifecycleToolsConfig = z.output<typeof LifecycleToolsConfigSchema>;
+
+export { LIFECYCLE_TOOL_NAMES, type LifecycleToolName, type LifecycleToolsConfig, LifecycleToolsConfigSchema };

package/dist/tool-factory-config.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+declare const LIFECYCLE_TOOL_NAMES: readonly ["view_logs", "search_history", "memory_list", "memory_get", "memory_create", "memory_update", "memory_delete"];
+type LifecycleToolName = (typeof LIFECYCLE_TOOL_NAMES)[number];
+declare const LifecycleToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lifecycle-tools">;
+    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["view_logs", "search_history", "memory_list", "memory_get", "memory_create", "memory_update", "memory_delete"]>, "many">>;
+    maxLogLines: z.ZodDefault<z.ZodNumber>;
+    maxLogBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "lifecycle-tools";
+    maxLogLines: number;
+    maxLogBytes: number;
+    enabledTools?: ("view_logs" | "search_history" | "memory_list" | "memory_get" | "memory_create" | "memory_update" | "memory_delete")[] | undefined;
+}, {
+    type: "lifecycle-tools";
+    enabledTools?: ("view_logs" | "search_history" | "memory_list" | "memory_get" | "memory_create" | "memory_update" | "memory_delete")[] | undefined;
+    maxLogLines?: number | undefined;
+    maxLogBytes?: number | undefined;
+}>;
+type LifecycleToolsConfig = z.output<typeof LifecycleToolsConfigSchema>;
+
+export { LIFECYCLE_TOOL_NAMES, type LifecycleToolName, type LifecycleToolsConfig, LifecycleToolsConfigSchema };

package/dist/tool-factory-config.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+const DEFAULT_MAX_LOG_LINES = 200;
+const DEFAULT_MAX_LOG_BYTES = 2e5;
+const LIFECYCLE_TOOL_NAMES = [
+  "view_logs",
+  "search_history",
+  "memory_list",
+  "memory_get",
+  "memory_create",
+  "memory_update",
+  "memory_delete"
+];
+const LifecycleToolsConfigSchema = z.object({
+  type: z.literal("lifecycle-tools"),
+  enabledTools: z.array(z.enum(LIFECYCLE_TOOL_NAMES)).optional().describe(
+    `Subset of tools to enable. If not specified, all tools are enabled. Available: ${LIFECYCLE_TOOL_NAMES.join(", ")}`
+  ),
+  maxLogLines: z.number().int().positive().default(DEFAULT_MAX_LOG_LINES).describe(
+    `Maximum number of log lines view_logs may return (default: ${DEFAULT_MAX_LOG_LINES})`
+  ),
+  maxLogBytes: z.number().int().positive().default(DEFAULT_MAX_LOG_BYTES).describe(
+    `Maximum bytes read from the end of the log file (default: ${DEFAULT_MAX_LOG_BYTES})`
+  )
+}).strict();
+export {
+  LIFECYCLE_TOOL_NAMES,
+  LifecycleToolsConfigSchema
+};

package/dist/tool-factory.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_factory_exports = {};
+__export(tool_factory_exports, {
+  lifecycleToolsFactory: () => lifecycleToolsFactory
+});
+module.exports = __toCommonJS(tool_factory_exports);
+var import_tool_factory_config = require("./tool-factory-config.js");
+var import_view_logs_tool = require("./view-logs-tool.js");
+var import_memory_tools = require("./memory-tools.js");
+var import_search_history_tool = require("./search-history-tool.js");
+const lifecycleToolsFactory = {
+  configSchema: import_tool_factory_config.LifecycleToolsConfigSchema,
+  metadata: {
+    displayName: "Lifecycle Tools",
+    description: "Self-observation tools (logs, memories)",
+    category: "lifecycle"
+  },
+  create: (config) => {
+    const toolCreators = {
+      view_logs: () => (0, import_view_logs_tool.createViewLogsTool)({
+        maxLogLines: config.maxLogLines,
+        maxLogBytes: config.maxLogBytes
+      }),
+      search_history: () => (0, import_search_history_tool.createSearchHistoryTool)(),
+      memory_list: () => (0, import_memory_tools.createMemoryListTool)(),
+      memory_get: () => (0, import_memory_tools.createMemoryGetTool)(),
+      memory_create: () => (0, import_memory_tools.createMemoryCreateTool)(),
+      memory_update: () => (0, import_memory_tools.createMemoryUpdateTool)(),
+      memory_delete: () => (0, import_memory_tools.createMemoryDeleteTool)()
+    };
+    const toolsToCreate = config.enabledTools ?? import_tool_factory_config.LIFECYCLE_TOOL_NAMES;
+    return toolsToCreate.map((toolName) => toolCreators[toolName]());
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  lifecycleToolsFactory
+});

package/dist/tool-factory.d.cts

@@ -0,0 +1,7 @@
+import { ToolFactory } from '@dexto/agent-config';
+import { LifecycleToolsConfig } from './tool-factory-config.cjs';
+import 'zod';
+
+declare const lifecycleToolsFactory: ToolFactory<LifecycleToolsConfig>;
+
+export { lifecycleToolsFactory };

package/dist/tool-factory.d.ts

@@ -0,0 +1,7 @@
+import { ToolFactory } from '@dexto/agent-config';
+import { LifecycleToolsConfig } from './tool-factory-config.js';
+import 'zod';
+
+declare const lifecycleToolsFactory: ToolFactory<LifecycleToolsConfig>;
+
+export { lifecycleToolsFactory };

package/dist/tool-factory.js

@@ -0,0 +1,40 @@
+import {
+  LifecycleToolsConfigSchema,
+  LIFECYCLE_TOOL_NAMES
+} from "./tool-factory-config.js";
+import { createViewLogsTool } from "./view-logs-tool.js";
+import {
+  createMemoryListTool,
+  createMemoryGetTool,
+  createMemoryCreateTool,
+  createMemoryUpdateTool,
+  createMemoryDeleteTool
+} from "./memory-tools.js";
+import { createSearchHistoryTool } from "./search-history-tool.js";
+const lifecycleToolsFactory = {
+  configSchema: LifecycleToolsConfigSchema,
+  metadata: {
+    displayName: "Lifecycle Tools",
+    description: "Self-observation tools (logs, memories)",
+    category: "lifecycle"
+  },
+  create: (config) => {
+    const toolCreators = {
+      view_logs: () => createViewLogsTool({
+        maxLogLines: config.maxLogLines,
+        maxLogBytes: config.maxLogBytes
+      }),
+      search_history: () => createSearchHistoryTool(),
+      memory_list: () => createMemoryListTool(),
+      memory_get: () => createMemoryGetTool(),
+      memory_create: () => createMemoryCreateTool(),
+      memory_update: () => createMemoryUpdateTool(),
+      memory_delete: () => createMemoryDeleteTool()
+    };
+    const toolsToCreate = config.enabledTools ?? LIFECYCLE_TOOL_NAMES;
+    return toolsToCreate.map((toolName) => toolCreators[toolName]());
+  }
+};
+export {
+  lifecycleToolsFactory
+};

package/dist/view-logs-tool.cjs

@@ -0,0 +1,183 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var view_logs_tool_exports = {};
+__export(view_logs_tool_exports, {
+  createViewLogsTool: () => createViewLogsTool
+});
+module.exports = __toCommonJS(view_logs_tool_exports);
+var fs = __toESM(require("node:fs/promises"), 1);
+var import_zod = require("zod");
+var import_core = require("@dexto/core");
+const LOG_LEVEL_VALUES = ["debug", "info", "warn", "error", "silly"];
+const ViewLogsInputSchema = import_zod.z.object({
+  lines: import_zod.z.number().int().positive().optional().default(200).describe("Number of log lines to return from the end of the log file"),
+  query: import_zod.z.string().optional().describe("Optional: filter logs by substring match (case-insensitive)"),
+  level: import_zod.z.union([import_zod.z.enum(LOG_LEVEL_VALUES), import_zod.z.array(import_zod.z.enum(LOG_LEVEL_VALUES))]).optional().describe("Optional: filter logs by level"),
+  component: import_zod.z.string().optional().describe("Optional: filter logs by component"),
+  includeContext: import_zod.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 (0, import_core.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 import_core.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 }
+      };
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createViewLogsTool
+});

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

@@ -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 };