Standardize and enhance error handling across hooks and worker service (#295)
* Enhance error logging in hooks
- Added detailed error logging in context-hook, new-hook, save-hook, and summary-hook to capture status, project, port, and relevant session information on failures.
- Improved error messages thrown in save-hook and summary-hook to include specific context about the failure.
* Refactor migration logging to use console.log instead of console.error
- Updated SessionSearch and SessionStore classes to replace console.error with console.log for migration-related messages.
- Added notes in the documentation to clarify the use of console.log for migration messages due to the unavailability of the structured logger during constructor execution.
* Refactor SDKAgent and silent-debug utility to simplify error handling
- Updated SDKAgent to use direct defaults instead of happy_path_error__with_fallback for non-critical fields such as last_user_message, last_assistant_message, title, filesRead, filesModified, concepts, and summary.request.
- Enhanced silent-debug documentation to clarify appropriate use cases for happy_path_error__with_fallback, emphasizing its role in handling unexpected null/undefined values while discouraging its use for nullable fields with valid defaults.
* fix: correct happy_path_error__with_fallback usage to prevent false errors
Fixes false "Missing cwd" and "Missing transcript_path" errors that were
flooding silent.log even when values were present.
Root cause: happy_path_error__with_fallback was being called unconditionally
instead of only when the value was actually missing.
Pattern changed from:
value: happy_path_error__with_fallback('Missing', {}, value || '')
To correct usage:
value: value || happy_path_error__with_fallback('Missing', {}, '')
Fixed in:
- src/hooks/save-hook.ts (PostToolUse hook)
- src/hooks/summary-hook.ts (Stop hook)
- src/services/worker/http/routes/SessionRoutes.ts (2 instances)
Impact: Eliminates false error noise, making actual errors visible.
Addresses issue #260 - users were seeing "Missing cwd" errors despite
Claude Code correctly passing all required fields.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Enhance error logging and handling across services
- Improved error messages in SessionStore to include project context when fetching boundary observations and timestamps.
- Updated ChromaSync error handling to provide more informative messages regarding client initialization failures, including the project context.
- Enhanced error logging in WorkerService to include the package path when reading version fails.
- Added detailed error logging in worker-utils to capture expected and running versions during health checks.
- Extended WorkerErrorMessageOptions to include actualError for more informative restart instructions.
* Refactor error handling in hooks to use standardized fetch error handler
- Introduced a new error handler `handleFetchError` in `shared/error-handler.ts` to standardize logging and user-facing error messages for fetch failures across hooks.
- Updated `context-hook.ts`, `new-hook.ts`, `save-hook.ts`, and `summary-hook.ts` to utilize the new error handler, improving consistency and maintainability.
- Removed redundant imports and error handling logic related to worker restart instructions from the hooks.
* feat: add comprehensive error handling tests for hooks and ChromaSync client
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Newman
@@ -11,7 +11,7 @@ import { stdin } from "process";
|
||||
import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
|
||||
import { HOOK_TIMEOUTS } from "../shared/hook-constants.js";
|
||||
import { handleWorkerError } from "../shared/hook-error-handler.js";
|
||||
import { getWorkerRestartInstructions } from "../utils/error-messages.js";
|
||||
import { handleFetchError } from "./shared/error-handler.js";
|
||||
|
||||
export interface SessionStartInput {
|
||||
session_id: string;
|
||||
@@ -35,7 +35,12 @@ async function contextHook(input?: SessionStartInput): Promise<string> {
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
|
||||
handleFetchError(response, errorText, {
|
||||
hookName: 'context',
|
||||
operation: 'Context generation',
|
||||
project,
|
||||
port
|
||||
});
|
||||
}
|
||||
|
||||
const result = await response.text();
|
||||
|
||||
+14
-3
@@ -4,7 +4,7 @@ import { createHookResponse } from './hook-response.js';
|
||||
import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
|
||||
import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
|
||||
import { handleWorkerError } from '../shared/hook-error-handler.js';
|
||||
import { getWorkerRestartInstructions } from '../utils/error-messages.js';
|
||||
import { handleFetchError } from './shared/error-handler.js';
|
||||
|
||||
export interface UserPromptSubmitInput {
|
||||
session_id: string;
|
||||
@@ -53,7 +53,12 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
|
||||
|
||||
if (!initResponse.ok) {
|
||||
const errorText = await initResponse.text();
|
||||
throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
|
||||
handleFetchError(initResponse, errorText, {
|
||||
hookName: 'new',
|
||||
operation: 'Session initialization',
|
||||
project,
|
||||
port
|
||||
});
|
||||
}
|
||||
|
||||
const initResult = await initResponse.json();
|
||||
@@ -87,7 +92,13 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
|
||||
handleFetchError(response, errorText, {
|
||||
hookName: 'new',
|
||||
operation: 'SDK agent start',
|
||||
project,
|
||||
port,
|
||||
sessionId: String(sessionDbId)
|
||||
});
|
||||
}
|
||||
} catch (error: any) {
|
||||
handleWorkerError(error);
|
||||
|
||||
+10
-7
@@ -13,7 +13,7 @@ import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
|
||||
import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
|
||||
import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
|
||||
import { handleWorkerError } from '../shared/hook-error-handler.js';
|
||||
import { getWorkerRestartInstructions } from '../utils/error-messages.js';
|
||||
import { handleFetchError } from './shared/error-handler.js';
|
||||
|
||||
export interface PostToolUseInput {
|
||||
session_id: string;
|
||||
@@ -54,10 +54,10 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
|
||||
tool_name,
|
||||
tool_input,
|
||||
tool_response,
|
||||
cwd: happy_path_error__with_fallback(
|
||||
cwd: cwd || happy_path_error__with_fallback(
|
||||
'Missing cwd in PostToolUse hook input',
|
||||
{ session_id, tool_name },
|
||||
cwd || ''
|
||||
''
|
||||
)
|
||||
}),
|
||||
signal: AbortSignal.timeout(HOOK_TIMEOUTS.DEFAULT)
|
||||
@@ -65,10 +65,13 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
logger.failure('HOOK', 'Failed to send observation', {
|
||||
status: response.status
|
||||
}, errorText);
|
||||
throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
|
||||
handleFetchError(response, errorText, {
|
||||
hookName: 'save',
|
||||
operation: 'Observation storage',
|
||||
toolName: tool_name,
|
||||
sessionId: session_id,
|
||||
port
|
||||
});
|
||||
}
|
||||
|
||||
logger.debug('HOOK', 'Observation sent successfully', { toolName: tool_name });
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
import { logger } from '../../utils/logger.js';
|
||||
import { getWorkerRestartInstructions } from '../../utils/error-messages.js';
|
||||
|
||||
export interface HookErrorContext {
|
||||
hookName: string;
|
||||
operation: string;
|
||||
project?: string;
|
||||
sessionId?: string;
|
||||
toolName?: string;
|
||||
port?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Standardized error handler for hook fetch failures.
|
||||
*
|
||||
* This function:
|
||||
* 1. Logs the error with full context to worker logs
|
||||
* 2. Throws a user-facing error with restart instructions
|
||||
*
|
||||
* Use this for all fetch errors in hooks to ensure consistent error handling.
|
||||
*/
|
||||
export function handleFetchError(
|
||||
response: Response,
|
||||
errorText: string,
|
||||
context: HookErrorContext
|
||||
): never {
|
||||
logger.error('HOOK', `${context.operation} failed`, {
|
||||
status: response.status,
|
||||
...context
|
||||
}, errorText);
|
||||
|
||||
const userMessage = context.toolName
|
||||
? `Failed ${context.operation} for ${context.toolName}: ${getWorkerRestartInstructions()}`
|
||||
: `${context.operation} failed: ${getWorkerRestartInstructions()}`;
|
||||
|
||||
throw new Error(userMessage);
|
||||
}
|
||||
@@ -16,8 +16,8 @@ import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
|
||||
import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
|
||||
import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
|
||||
import { handleWorkerError } from '../shared/hook-error-handler.js';
|
||||
import { handleFetchError } from './shared/error-handler.js';
|
||||
import { extractLastMessage } from '../shared/transcript-parser.js';
|
||||
import { getWorkerRestartInstructions } from '../utils/error-messages.js';
|
||||
|
||||
export interface StopInput {
|
||||
session_id: string;
|
||||
@@ -41,10 +41,10 @@ async function summaryHook(input?: StopInput): Promise<void> {
|
||||
const port = getWorkerPort();
|
||||
|
||||
// Extract last user AND assistant messages from transcript
|
||||
const transcriptPath = happy_path_error__with_fallback(
|
||||
const transcriptPath = input.transcript_path || happy_path_error__with_fallback(
|
||||
'Missing transcript_path in Stop hook input',
|
||||
{ session_id },
|
||||
input.transcript_path || ''
|
||||
''
|
||||
);
|
||||
const lastUserMessage = extractLastMessage(transcriptPath, 'user');
|
||||
const lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);
|
||||
@@ -70,10 +70,12 @@ async function summaryHook(input?: StopInput): Promise<void> {
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
logger.failure('HOOK', 'Failed to generate summary', {
|
||||
status: response.status
|
||||
}, errorText);
|
||||
throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
|
||||
handleFetchError(response, errorText, {
|
||||
hookName: 'summary',
|
||||
operation: 'Summary generation',
|
||||
sessionId: session_id,
|
||||
port
|
||||
});
|
||||
}
|
||||
|
||||
logger.debug('HOOK', 'Summary request sent successfully');
|
||||
|
||||
Reference in New Issue
Block a user