timifaloye/bookly-support-agent

Purpose and Entry Points

Bookly Support Agent is a Node.js/TypeScript prototype for SMS/iMessage bookstore support. It accepts customer messages, maintains conversation context, uses LLMs to classify and answer requests, invokes order/return tools, and performs an asynchronous response-accuracy check.

Local CLI execution starts from src/index.ts. The production messaging path is the OSIS webhook server in src/server.ts, which delegates inbound events to src/osis/webhookHandler.ts.

OSIS Ingress and Webhook Safety

The OSIS adapter validates, parses, logs, and deduplicates inbound provider webhooks before agent processing:

• src/osis/webhookHandler.ts

• src/osis/signature.ts

• src/osis/webhookPayload.ts

Duplicate protection is backed by SQLite through src/osis/sqliteDedupeTracker.ts; this preserves idempotency across development-server restarts. The OSIS client in src/osis/client.ts is the outbound messaging boundary and requires OSIS credentials.

Conversation Persistence

Conversation history is abstracted behind a store and persisted in SQLite for the webhook runtime:

• src/state/conversationStore.ts

• src/state/sqliteConversationStore.ts

The agent retrieves prior turns for each customer/channel conversation, appends the inbound message and generated response, and supplies history to the model pipeline. This separates stateful conversations from stateless business tools.

Agent Orchestration and LLM Pipeline

src/claude/agent.ts is the central coordinator. It runs a three-stage flow:

1. classify user intent;

2. generate a tool-aware support reply;

3. run a background hallucination/accuracy check.

Core model-facing modules are:

• src/claude/intentClassifier.ts

• src/claude/systemPrompt.ts

• src/claude/hallucinationCheck.ts

Anthropic is the primary Claude integration; OpenAI is also required by the application, likely for the accuracy-check stage. Tool execution is mediated rather than directly exposed to model logic via src/claude/tools.ts and src/claude/toolExecutor.ts.

Intent, Tool, and Policy Boundary

Customer requests are mapped to a constrained support domain: verification, order status, return eligibility, and return creation:

• src/tools/verifyCustomer.ts

• src/tools/getOrderStatus.ts

• src/tools/checkReturnEligibility.ts

• src/tools/createReturnRequest.ts

Return decision logic is separated from tool transport in src/tools/returnEligibility.ts. The tools read/update prototype business records and policies through:

• src/data/orders.ts

• src/data/policy.ts

• src/data/returnRequests.ts

This boundary keeps LLM output from directly mutating data; return creation is an explicit tool action.

Return Confirmation and Email

After creating a return request, confirmation content and delivery are handled outside the core agent:

• src/claude/returnConfirmationMessage.ts

• src/lib/confirmation.ts

• src/lib/email.ts

src/lib/resendEmailClient.ts integrates Resend when RESEND_API_KEY is configured; otherwise confirmations are recorded without actual delivery. This makes email an optional external side effect rather than a prerequisite for request creation.

Runtime and Operational Constraints

The runtime is Node.js 24+ with TypeScript. Required external services are Anthropic, OpenAI, and, for live messaging, OSIS; Resend is optional. SQLite supports both conversation persistence and webhook deduplication. src/lib/devWatchWarning.ts reflects an operational distinction: auto-restart development mode is not intended for real webhook traffic despite durable local SQLite state.