bashkit 0.3.1 → 0.4.0

package/dist/utils/debug.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Debug logging utilities for bashkit tools.
+ *
+ * Enable debug logging via environment variable:
+ * - BASHKIT_DEBUG=1 or BASHKIT_DEBUG=stderr - Human readable output to stderr
+ * - BASHKIT_DEBUG=json - JSON lines to stderr
+ * - BASHKIT_DEBUG=memory - In-memory array (retrieve via getDebugLogs())
+ * - BASHKIT_DEBUG=file:/path/to/trace.jsonl - Write to file
+ */
+/** Debug event structure for tool execution tracing */
+export interface DebugEvent {
+    /** Unique ID to correlate start/end events (e.g., "grep-1") */
+    id: string;
+    /** Timestamp in milliseconds */
+    ts: number;
+    /** Tool name */
+    tool: string;
+    /** Event type */
+    event: "start" | "end" | "error";
+    /** Input parameters (start events only, summarized) */
+    input?: unknown;
+    /** Output data (end events only, summarized) */
+    output?: unknown;
+    /** Key metrics like exitCode, matchCount, etc. */
+    summary?: Record<string, unknown>;
+    /** Duration in milliseconds (end events only) */
+    duration_ms?: number;
+    /** Parent event ID for nested tool calls (e.g., task → subagent tools) */
+    parent?: string;
+    /** Error message (error events only) */
+    error?: string;
+}
+/**
+ * Checks if debug mode is enabled (any mode except "off").
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Summarize data for debug output.
+ * - Truncates strings to 1000 chars
+ * - Limits arrays to 10 items
+ * - Recursively summarizes nested objects
+ */
+export declare function summarize(data: unknown, depth?: number): unknown;
+/**
+ * Record the start of a tool execution.
+ * @returns Event ID to correlate with debugEnd/debugError
+ */
+export declare function debugStart(tool: string, input?: Record<string, unknown>): string;
+/**
+ * Record the successful end of a tool execution.
+ */
+export declare function debugEnd(id: string, tool: string, options: {
+    output?: unknown;
+    summary?: Record<string, unknown>;
+    duration_ms: number;
+}): void;
+/**
+ * Record an error during tool execution.
+ */
+export declare function debugError(id: string, tool: string, error: string | Error): void;
+/**
+ * Push a parent context for nested tool calls (e.g., when Task starts a subagent).
+ */
+export declare function pushParent(id: string): void;
+/**
+ * Pop the current parent context.
+ */
+export declare function popParent(): void;
+/**
+ * Get all debug logs (memory mode only).
+ * @returns Array of debug events, or empty array if not in memory mode
+ */
+export declare function getDebugLogs(): DebugEvent[];
+/**
+ * Clear all debug logs (memory mode).
+ * Call this between agent runs to reset the trace.
+ */
+export declare function clearDebugLogs(): void;
+/**
+ * Force re-initialization of debug mode from environment.
+ * Useful for testing or when environment changes.
+ */
+export declare function reinitDebugMode(): void;

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export { type CompactConversationConfig, type CompactConversationResult, type CompactConversationState, compactConversation, createCompactConfig, MODEL_CONTEXT_LIMITS, type ModelContextLimit, } from "./compact-conversation";
 export { type ContextMetrics, type ContextStatus, type ContextStatusConfig, type ContextStatusLevel, contextNeedsAttention, contextNeedsCompaction, getContextStatus, } from "./context-status";
+export { type DebugEvent, clearDebugLogs, getDebugLogs, isDebugEnabled, reinitDebugMode, } from "./debug";
 export { estimateMessagesTokens, estimateMessageTokens, estimateTokens, type PruneMessagesConfig, pruneMessagesByTokens, } from "./prune-messages";