Equanaut AI Assistant

AI-powered assistant with chat, tool execution, confirmation workflows, context assembly, onboarding pipeline, and security guardrails

SPEC 018 — Equanaut AI Assistant

Field	Value
Status	DRAFT
Priority	P1 — Core Platform
Backend	equa-server/modules/agent/
Frontend	equa-web/src/modules/equanaut/
Endpoints	equa-server/modules/agent/src/endpoints/agent-endpoints.ts
Model	claude-sonnet-4-20250514 (default, configurable via EQUANAUT_MODEL / AGENT_MODEL)
Env	ANTHROPIC_API_KEY (required), AGENT_ENABLED (optional kill switch)

---

1. Feature Purpose

Equanaut is the AI assistant embedded in the Equa platform. It provides a conversational interface for users to query and manage their organizations, cap tables, members, documents, and equity plans. The assistant uses Claude with tool-calling to execute read and write operations on the user’s behalf, with a security layer that requires explicit confirmation for write/destructive operations. A secondary onboarding pipeline uses the same AI infrastructure to analyze uploaded documents and set up organizations for new users.

---

2. Current State (Verified)

2.1 Agent Service (Backend Core)

Detail	Value
File	equa-server/modules/agent/src/agent-service.ts
Class	AgentService
SDK	@anthropic-ai/sdk
Model	Configurable, default claude-sonnet-4-20250514
Max tokens	Configurable, default 4096
Components	ContextAssembler, ToolExecutor, Guardrails, AuditLogger, PermissionProxy
Message flow	1. Permission check → 2. Context assembly → 3. Tool filtering by permissions → 4. Claude API call → 5. Tool execution loop → 6. Response

2.2 Tool System

Detail	Value
File	equa-server/modules/agent/src/tools/definitions.ts
Categories	ToolCategory.Read, ToolCategory.Write, ToolCategory.Destructive
Confirmation	Write tools require single confirmation; Destructive tools require double confirmation; Read tools execute immediately
Permission filtering	filterToolsByPermissions() — only shows tools the user has permission for
Tool catalogs	catalog/organization.ts, catalog/members.ts, catalog/captable.ts, catalog/documents.ts, catalog/plans.ts, catalog/roles.ts
Executor	equa-server/modules/agent/src/tools/executor.ts — ToolExecutor.execute()

Tool Categories (from source):

Category	Tools	Confirmation
Organization	listOrganizations, getOrganization, getOrganizationDashboard, updateOrganization	Read: none, Write: single
Members	listMembers, getMember, addMember, updateMember, removeMember	Read: none, Write: single, Destructive: double
Cap Table	getCapTable, getSecurityTypes, createSecurityType, createShareholding	Read: none, Write: single
Documents	listDocuments, getDocument, createFolder, moveDocument	Read: none, Write: single
Plans	listPlans, getPlan, createPlan, createGrant	Read: none, Write: single
Roles	listRoles, getRole, createRole, updateRole	Read: none, Write: single

2.3 Security & Guardrails

Detail	Value
File	equa-server/modules/agent/src/security/guardrails.ts
Rate limits (defaults)	30 tool calls/min, 10 write ops/min, 5 destructive ops/hour
Confirmation expiry	5 minutes
Confirmation states	claimed flag prevents race conditions (TOCTOU protection)
Permission proxy	equa-server/modules/agent/src/security/permission-proxy.ts — validates org access and retrieves user permissions
Audit logging	Every tool call logged with user, org, tool name, arguments, result status, execution time

2.4 Context Assembly

Detail	Value
File	equa-server/modules/agent/src/context/assembler.ts
Class	ContextAssembler
Builds	UserContext (id, email, name, org list) + OrganizationContext (id, name, type, stats) + ContextSummaries (cap table, members, documents)
Summarizer	equa-server/modules/agent/src/context/summarizer.ts — converts context to text for system prompt

2.5 Pending Confirmations

Detail	Value
Storage	In-memory Map<string, PendingConfirmation> on AgentService
Confirmation flow	1. Tool requires confirmation → 2. Store pending + return confirmation_required → 3. User confirms/cancels via /agent/confirm → 4. Execute or abort
Expiry cleanup	cleanupExpiredConfirmations() runs on each confirmAction() call
Persistence caveat	In-memory only — lost on server restart (noted as TODO)

2.6 Onboarding Pipeline

Detail	Value
Files	equa-server/modules/agent/src/onboarding/onboarding-service.ts, onboarding-repository.ts, organization-builder.ts, context-analyzer.ts, clarification-engine.ts, file-processor.ts
Parsers	parsers/pdf-parser.ts, parsers/excel-parser.ts
Status flow	pending_signup → pending_setup → setting_up → ready → first_login → completed
Analysis	Extracts entities (founders, investors, employees), equity info, security types, confidence scores
Clarification	Generates questions when confidence is below threshold; supports iterative Q&A
Showcase	Presents extracted data for user review with inline editing (corrections)

2.7 System Prompt

Detail	Value
Identity	”You are Equanaut, an AI assistant for the Equa platform”
Context injection	User name, org name, org stats, cap table summary, member summary, document summary
Guidelines	Read ops: proactive data gathering. Write ops: explain before execute, require confirmation. Destructive: extra caution, impact explanation.
Constraints	Never guess data, respect permissions, USD default, YYYY-MM-DD dates, precise share numbers

2.8 Frontend API Configuration

Detail	Value
File	equa-web/src/modules/equanaut/services/api/config.ts
Base URL	window.__EQUANAUT_CONFIG__.apiUrl → EQUANAUT_API_URL → /equanaut-api (fallback)
Model	window.__EQUANAUT_CONFIG__.model → EQUANAUT_MODEL → claude-sonnet-4-20250514
Webpack proxy	/equanaut-api → localhost:19792 or Hetzner server
Timeout	60,000ms
Retry	2 attempts, 1s initial delay, 10s max, 1.5x timeout multiplier

---

3. Data Model

AgentConfig

Field	Type	Default
apiKey	string	ANTHROPIC_API_KEY env
model	string	claude-sonnet-4-20250514
maxTokens	number	4096
maxToolCallsPerMinute	number	30
maxWriteOperationsPerMinute	number	10
maxDestructivePerHour	number	5
confirmWriteOperations	boolean	true

ToolDefinition

Field	Type	Description
name	string	Tool identifier
description	string	Human-readable description
category	ToolCategory	read, write, or destructive
inputSchema	ToolInputSchema	JSON Schema for tool parameters
requiredPermission	string?	Permission needed to access tool
confirmationRequired	boolean	Auto-true for write/destructive
doubleConfirmRequired	boolean?	Auto-true for destructive

PendingConfirmation (in-memory)

Field	Type	Description
id	string	UUID
toolCall	ToolCall	Tool name + input
userId	Uuid	Requesting user
organizationId	Uuid	Target organization
conversationId	string	Chat session ID
claudeMessages	any[]	Message history for continuation
priorToolResults	any[]	Results from batch tools before this confirmation
createdAt	Date
expiresAt	Date	5 minutes from creation
claimed	boolean	TOCTOU protection

AgentAuditLog

Field	Type	Description
type	string	Always agent_action
user	Uuid	Acting user
organization	Uuid	Target organization
data.tool	string	Tool name
data.arguments	object	Tool input
data.result	string	success, failed, or cancelled
data.conversationId	string	Chat session
data.timestamp	Date
data.executionTimeMs	number?	Execution duration

OnboardingContext

Field	Type	Description
id	string	UUID
userId	Uuid?	Linked after signup
email	string	User email
initialPrompt	string	Free-text describing the organization
status	OnboardingStatus	Status enum
setupResult	OnboardingSetupResult?	Organization build result
analysisResult	OnboardingAnalysisResult?	AI analysis output
clarifyingQuestions	ClarifyingQuestion[]?	Generated questions
confidenceScores	object?	Per-category confidence
createdAt / updatedAt / expiresAt	Date	Timestamps

---

4. API Endpoints

Chat & Tools

Method	Path	Auth	Description
GET	/api/v1/agent/status	None	Health check — returns { enabled: true, version: '1.0.0' }
POST	/api/v1/agent/chat	Session + canViewOrganization	Send message, receive response or confirmation request
POST	/api/v1/agent/confirm	Session	Confirm or cancel a pending action
GET	/api/v1/organization/:organization/agent/context	Session + canViewOrganization	Get assembled context for an organization
GET	/api/v1/organization/:organization/agent/tools	Session + canViewOrganization	List available tools filtered by user permissions

Onboarding (Authenticated)

Method	Path	Auth	Description
POST	/api/v1/agent/onboarding/link	Session	Link authenticated user to pre-existing onboarding context
POST	/api/v1/agent/onboarding/setup	Session	Trigger organization setup from onboarding context
GET	/api/v1/agent/onboarding/first-login	Session	Check for pending onboarding on first login
POST	/api/v1/agent/onboarding/complete	Session	Mark onboarding as completed
POST	/api/v1/agent/onboarding/analyze	Session	Trigger AI analysis of onboarding context
POST	/api/v1/agent/onboarding/build	Session	Build organization from analysis results
POST	/api/v1/agent/onboarding/clarify	Session	Submit answer to clarifying question
POST	/api/v1/agent/onboarding/correct	Session	Submit correction to showcase item

Onboarding (Public)

Method	Path	Auth	Description
POST	/api/v1/agent/onboarding/create	Public	Create onboarding context (pre-registration)
GET	/api/v1/agent/onboarding/:id	Public	Retrieve onboarding context
GET	/api/v1/agent/onboarding/analysis-status/:id	Public	Check analysis completion status
GET	/api/v1/agent/onboarding/questions/:id	Public	Get clarifying questions
GET	/api/v1/agent/onboarding/showcase/:id	Public	Get showcase data for review

---

5. Frontend Components

Module: equa-web/src/modules/equanaut/

Core Components:

Component	File	Purpose
EquanautSidebar	components/EquanautSidebar.tsx	Main sidebar container for the assistant
ChatContainer	components/ChatContainer.tsx	Chat message list with scroll management
ChatInput	components/ChatInput.tsx	Message input with send button
ChatMessage	components/ChatMessage.tsx	Individual message bubble (user/assistant)
Header	components/Header.tsx	Sidebar header with title and controls
StatusBar	components/StatusBar.tsx	Connection/loading status display
MarkdownRenderer	components/MarkdownRenderer.tsx	Renders assistant markdown responses
Icons	components/Icons.tsx	SVG icon components

Tool Execution & Confirmation:

Component	File	Purpose
ToolExecutionPanel	components/ToolExecutionPanel.tsx	Displays executing tool steps with status indicators
ConfirmationDialog	components/ConfirmationDialog.tsx	Confirm/cancel dialog for write operations
ConfidenceBadge	components/ConfidenceBadge.tsx	Confidence score indicator

Conversation Management:

Component	File	Purpose
ConversationList	components/ConversationList.tsx	List of past conversations
ConversationItem	components/ConversationItem.tsx	Single conversation entry
MessageFeedback	components/MessageFeedback.tsx	Thumbs up/down feedback on messages

Onboarding Flow:

Component	File	Purpose
OnboardingFlow	components/OnboardingFlow.tsx	AI-guided onboarding experience
MVPShowcase	components/MVPShowcase.tsx	Preview of extracted organization data
ShowcaseItem	components/ShowcaseItem.tsx	Individual item with confidence and edit
InlineEditor	components/InlineEditor.tsx	In-place editing for corrections
ClarifyingQuestionsFlow	components/ClarifyingQuestionsFlow.tsx	Q&A flow for missing information
ClarifyingQuestion	components/ClarifyingQuestion.tsx	Single question with suggested answers

Services:

Service	File	Purpose
agentService	services/api/agent/agent-service.ts	API client for all agent endpoints (chat, confirm, context, tools, onboarding)
ActionExecutor	services/ActionExecutor.ts	Client-side action execution orchestration
chat/messages	services/api/chat/messages.ts	Message formatting utilities

Context Providers:

Provider	File	Purpose
EquanautProvider	context/EquanautProvider.tsx	Top-level provider for Equanaut state
AgentContextProvider	context/AgentContextProvider.tsx	Agent context (org, tools) management
PageContextProvider	context/PageContextProvider.tsx	Current page context for the agent
FormRegistry	context/FormRegistry.tsx	Tracks active forms for context-aware assistance

Hooks:

Hook	File	Purpose
useAgentChat	hooks/useAgentChat.ts	Core chat state management (messages, loading, pending actions, conversation ID)
useChat	hooks/useChat.ts	Chat session management
useMessageFeedback	hooks/useMessageFeedback.ts	Feedback state for message ratings
useClickOutside	hooks/useClickOutside.ts	Click-outside handler for closing sidebar

---

6. Business Rules

1. Agent availability is gated by ANTHROPIC_API_KEY — if absent, isAgentEnabled() returns false and all endpoints return disabled status. Can also be explicitly disabled via AGENT_ENABLED=false.
2. Permission enforcement: Users can only access tools they have permissions for. filterToolsByPermissions() strips unauthorized tools from the Claude tool list.
3. Organization access: permissionProxy.hasOrganizationAccess() is checked before any chat request. Unauthorized users receive an error.
4. Confirmation flow: All write operations require user confirmation before execution. Destructive operations require double confirmation. Confirmations expire after 5 minutes.
5. Rate limiting: Per user-org pair — max 30 tool calls/min, 10 write ops/min, 5 destructive ops/hour (configurable via env).
6. Audit trail: Every tool execution is logged with user, org, tool, arguments, result, and timing.
7. Context injection: The system prompt includes organization stats, cap table summary, member summary, and document summary for grounded responses.
8. Batch tool execution: When Claude requests multiple tools, read-only tools execute immediately. The first write/destructive tool in a batch triggers confirmation, preserving prior tool results for continuation.
9. Onboarding public endpoints: create, get context, analysis-status, questions, and showcase are public (pre-registration). All mutation endpoints require authentication.
10. Onboarding expiry: Contexts have an expiresAt field; expired contexts transition to expired status.
11. Frontend retry: API calls retry up to 2 times with exponential backoff (1s initial, 10s max, 1.5x multiplier).

---

7. Acceptance Criteria

• User can open the Equanaut sidebar and send a chat message
• Agent responds with accurate information about the user’s organization
• Read-only tool calls execute without confirmation prompts
• Write operations display a confirmation dialog before execution
• Destructive operations display a double-confirmation dialog
• Confirmed actions execute and return results to the conversation
• Cancelled actions abort cleanly with a cancellation message
• Confirmation requests expire after 5 minutes
• Rate-limited requests return a clear error with retry timing
• Users without organization access receive a permission error
• Tool list is filtered to only show tools the user has permission for
• Onboarding flow: user can describe their company and get an AI-built organization
• Onboarding analysis extracts entities, equity info, and security types with confidence scores
• Clarifying questions flow works for ambiguous inputs
• Showcase displays extracted data with inline editing for corrections
• Agent audit log captures all tool executions
• Agent gracefully handles Anthropic API errors

---

8. Risks

Risk	Impact	Mitigation
Pending confirmations stored in memory	Lost on server restart, potential data loss if user confirmed mid-restart	Persist to database (noted as TODO in source)
Claude model costs per conversation	Uncontrolled spend with active users	Rate limiting exists; add per-user/per-org spend caps
Tool execution errors not rolled back	Partial state changes if multi-tool operation fails partway	Implement compensating transactions for critical write operations
Context assembly queries full DB on each message	Performance degradation with large organizations	Cache context with TTL; use buildWithSummaries (already summarizes)
Onboarding analysis confidence may be low	Users may get incorrect organization setup	Showcase review with inline corrections + clarifying questions mitigate this
Webpack proxy to localhost:19792 assumes local dev or Hetzner	Production deployment requires proper proxy/routing configuration	Document production deployment path with reverse proxy
No conversation persistence	Chat history lost on page refresh	Implement conversation storage (backend or localStorage)
window.__EQUANAUT_CONFIG__ global injection	Configuration scattered across webpack, env vars, and runtime globals	Consolidate to a single configuration source