Server Advanced Features

hooks.yaml --> DeclarativeHookRegistry --> ToolCallListener on Agent
                     |                          |
                     |                    PRE_TOOL_USE / POST_TOOL_USE
                     |
               DeclarativeHookExecutor
                     |
              COMMAND (shell) / LOG (message)

// Factory methods
HookAction cmd = HookAction.command("echo 'tool finished'");
HookAction log = HookAction.log("Tool ${tool} is about to execute");

// Exact match
HookMatcher exact = new HookMatcher("shell");
exact.matches("shell");    // true
exact.matches("Shell");    // true (case-insensitive)

// Glob wildcard
HookMatcher glob = new HookMatcher("file_*");
glob.matches("file_read");  // true
glob.matches("file_write"); // true
glob.matches("shell");      // false

// Match all tools
HookMatcher all = HookMatcher.ALL; // pattern "*"

// Record: HookConfig(event, matcher, action)
HookConfig config = new HookConfig(
    HookEvent.PRE_TOOL_USE,
    new HookMatcher("file_*"),
    HookAction.log("Tool ${tool} is about to execute")
);

@FunctionalInterface
public interface HookExecutor {
    void execute(HookAction action, Map<String, String> context);
}

hooks:
  - event: preToolUse
    matcher: "file_*"
    action:
      type: log
      message: "Tool ${tool} is about to execute"

  - event: postToolUse
    matcher: "shell"
    action:
      type: command
      command: "echo 'shell tool finished'"

  - event: onStart
    action:
      type: log
      message: "Agent started"

// Parse from YAML
InputStream yaml = new FileInputStream("hooks.yaml");
DeclarativeHookRegistry registry = DeclarativeHookRegistry.fromYaml(yaml);

// Parse with custom executor
DeclarativeHookRegistry registry = DeclarativeHookRegistry.fromYaml(yaml, customExecutor);

// Programmatic creation
DeclarativeHookRegistry registry = DeclarativeHookRegistry.of(hookConfigs);

// Apply to an agent (registers ToolCallListener + fires ON_START)
registry.applyTo(agent);

// Fire a generic event
registry.fireEvent(HookEvent.ON_START, Map.of("agent", agentId));

// Fire a tool-specific event (checks HookMatcher against tool name)
registry.fireToolEvent(HookEvent.PRE_TOOL_USE, "shell",
    Map.of("event", "preToolUse"));

List<HookConfig> all = registry.getHooks();
List<HookConfig> preHooks = registry.getHooksForEvent(HookEvent.PRE_TOOL_USE);

// Setup
Supplier<LLMClient> llmSupplier = () -> new AnthropicClient("claude-sonnet-4-20250514");
AgentFactory factory = new AgentFactory(llmSupplier);

// Or with a custom working directory
AgentFactory factory = new AgentFactory(llmSupplier, Path.of("/project"));

// Simple creation (role name only)
Agent agent = factory.createAgent("agent-001", "assistant");

// With additional tools (e.g., MCP proxy tools)
Agent agent = factory.createAgent("agent-001", "developer", additionalTools);

// With provider and model override
Agent agent = factory.createAgent("agent-001", "developer",
    "ollama", "glm-5:cloud", additionalTools);

// Full configuration with custom goal and domain
Agent agent = factory.createAgent("agent-001", "developer",
    "ollama", "glm-5:cloud",
    "Write clean, tested code for the TnsAI framework",
    "tnsai-core",
    additionalTools);

// Multi-role agent from RoleDef list
Agent agent = factory.createAgent("agent-001", "assistant",
    "ollama", "glm-5:cloud", roleDefs, additionalTools);

IdleShutdownManager manager = new IdleShutdownManager(
    connectionManager,           // WsConnectionManager instance
    Duration.ofMinutes(30),      // idle timeout
    () -> server.stop()          // shutdown action
);

manager.start();
// If no connections exist at start, schedules shutdown

// Called by WebSocket handlers
manager.onConnectionOpened();  // cancels pending shutdown
manager.onConnectionClosed();  // schedules shutdown if no connections remain

manager.stop();  // cleanup

RagService rag = new RagService();

// Index a directory
rag.indexDirectory(Path.of("/project/src"), progress ->
    System.out.printf("Indexing: %d/%d - %s%n",
        progress.indexedFiles(), progress.totalFiles(), progress.currentFile()));

// Search the knowledge base
List<SearchResult> results = rag.search("authentication logic", 5);

// Build a context-augmented prompt
String augmentedPrompt = rag.buildContextPrompt("How does auth work?", 3);
// Returns:
// [Relevant code context]
// --- file: src/main/java/Auth.java (lines 10-30) ---
// <chunk content>
//
// [User question]
// How does auth work?

// Add a document manually
String docId = rag.addDocument("Some text content",
    Map.of("source", "manual", "tag", "notes"));

// Remove a document
boolean removed = rag.removeDocument(docId);

// List all managed documents
List<RagService.DocumentInfo> docs = rag.listDocuments();
// DocumentInfo(id, preview, contentLength, metadata)

// Get a specific document
Optional<Document> doc = rag.getDocument(docId);

// Get index status
IndexStatus status = rag.getStatus();
// IndexStatus(fileCount, chunkCount, lastIndexedAt, indexedPath)

// Clear everything
rag.clear();

FileIndexer indexer = new FileIndexer();

FileIndexer.IndexResult result = indexer.index(
    Path.of("/project"),
    knowledgeBase,
    bm25Stream,
    progress -> System.out.println(progress.currentFile())
);
// IndexResult(fileCount, chunkCount)

// Force full re-index on next run
indexer.clearHashes();

// Chunk a file
List<Document> chunks = CodeChunker.chunk(
    Path.of("src/Auth.java"),  // file path (metadata)
    fileContent,                // file content string
    "java"                      // language key
);

// Detect language from filename
String lang = CodeChunker.detectLanguage("Auth.java");    // "java"
String lang = CodeChunker.detectLanguage("app.tsx");       // "tsx"
String lang = CodeChunker.detectLanguage("README.md");     // "md"
String lang = CodeChunker.detectLanguage("unknown.xyz");   // "text"