@townco/agent 0.1.44 → 0.1.45

package/dist/acp-server/adapter.d.ts

@@ -18,6 +18,7 @@ export declare class AgentAcpAdapter implements acp.Agent {
     private agent;
     private storage;
     private noSession;
+    private agentDir;
     constructor(agent: AgentRunner, connection: acp.AgentSideConnection, agentDir?: string, agentName?: string);
     initialize(_params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
     newSession(params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;

package/dist/acp-server/adapter.js

@@ -1,10 +1,71 @@
 import * as acp from "@agentclientprotocol/sdk";
+import { createLogger } from "@townco/core";
+import { HookExecutor, loadHookCallback } from "../runner/hooks";
 import { SessionStorage, } from "./session-storage.js";
+const logger = createLogger("adapter");
 /**
  * ACP extension key for subagent mode indicator
  * Following ACP extensibility pattern with namespaced key
  */
 export const SUBAGENT_MODE_KEY = "town.com/isSubagent";
+/**
+ * Create a context snapshot based on the previous context
+ * Preserves full messages from previous context and adds new pointers
+ */
+function createContextSnapshot(messageCount, timestamp, previousContext) {
+    const messages = [];
+    if (previousContext) {
+        // Start with all messages from previous context
+        messages.push(...previousContext.messages);
+        // Find the highest pointer index in previous context
+        let maxPointerIndex = -1;
+        for (const entry of previousContext.messages) {
+            if (entry.type === "pointer" && entry.index > maxPointerIndex) {
+                maxPointerIndex = entry.index;
+            }
+        }
+        // Add pointers for any new messages since the previous context
+        for (let i = maxPointerIndex + 1; i < messageCount; i++) {
+            messages.push({ type: "pointer", index: i });
+        }
+    }
+    else {
+        // No previous context, create pointers for all messages
+        for (let i = 0; i < messageCount; i++) {
+            messages.push({ type: "pointer", index: i });
+        }
+    }
+    return { timestamp, messages };
+}
+/**
+ * Resolve context entries to session messages
+ * Converts pointers to actual messages and includes full messages
+ */
+function resolveContextToMessages(context, allMessages) {
+    if (context.length === 0) {
+        return [];
+    }
+    // Use the latest context entry
+    const latestContext = context[context.length - 1];
+    if (!latestContext) {
+        return [];
+    }
+    const resolved = [];
+    for (const entry of latestContext.messages) {
+        if (entry.type === "pointer") {
+            // Resolve pointer to actual message
+            const message = allMessages[entry.index];
+            if (message) {
+                resolved.push(message);
+            }
+        }
+        else if (entry.type === "full") {
+            // Use full message directly
+            resolved.push(entry.message);
+        }
+    }
+    return resolved;
+}
 /** Adapts an Agent to speak the ACP protocol */
 export class AgentAcpAdapter {
     connection;
@@ -12,16 +73,18 @@ export class AgentAcpAdapter {
     agent;
     storage;
     noSession;
+    agentDir;
     constructor(agent, connection, agentDir, agentName) {
         this.connection = connection;
         this.sessions = new Map();
         this.agent = agent;
+        this.agentDir = agentDir;
         this.noSession = process.env.TOWN_NO_SESSION === "true";
         this.storage =
             agentDir && agentName && !this.noSession
                 ? new SessionStorage(agentDir, agentName)
                 : null;
-        console.log("[adapter] Initialized with:", {
+        logger.info("Initialized with", {
             agentDir,
             agentName,
             noSession: this.noSession,
@@ -42,6 +105,7 @@ export class AgentAcpAdapter {
         this.sessions.set(sessionId, {
             pendingPrompt: null,
             messages: [],
+            context: [],
             requestParams: params,
         });
         return {
@@ -60,12 +124,13 @@ export class AgentAcpAdapter {
         this.sessions.set(params.sessionId, {
             pendingPrompt: null,
             messages: storedSession.messages,
+            context: storedSession.context,
             requestParams: { cwd: process.cwd(), mcpServers: [] },
         });
         // Replay conversation history to client with ordered content blocks
-        console.log(`[adapter] Replaying ${storedSession.messages.length} messages for session ${params.sessionId}`);
+        logger.info(`Replaying ${storedSession.messages.length} messages for session ${params.sessionId}`);
         for (const msg of storedSession.messages) {
-            console.log(`[adapter] Replaying message: ${msg.role} with ${msg.content.length} content blocks`);
+            logger.debug(`Replaying message: ${msg.role} with ${msg.content.length} content blocks`);
             // Iterate through content blocks in order
             for (const block of msg.content) {
                 if (block.type === "text") {
@@ -150,10 +215,11 @@ export class AgentAcpAdapter {
         let session = this.sessions.get(params.sessionId);
         // If session not found (e.g., after server restart), create a new one
         if (!session) {
-            console.log(`Session ${params.sessionId} not found, creating new session`);
+            logger.info(`Session ${params.sessionId} not found, creating new session`);
             session = {
                 pendingPrompt: null,
                 messages: [],
+                context: [],
                 requestParams: { cwd: process.cwd(), mcpServers: [] },
             };
             this.sessions.set(params.sessionId, session);
@@ -167,6 +233,11 @@ export class AgentAcpAdapter {
             .filter((p) => p.type === "text")
             .map((p) => p.text)
             .join("\n");
+        logger.info("User message received", {
+            sessionId: params.sessionId,
+            messagePreview: userMessageText.slice(0, 100),
+            noSession: this.noSession,
+        });
         // Only store messages if session persistence is enabled
         if (!this.noSession) {
             const userMessage = {
@@ -175,6 +246,12 @@ export class AgentAcpAdapter {
                 timestamp: new Date().toISOString(),
             };
             session.messages.push(userMessage);
+            // Create context snapshot based on previous context
+            const previousContext = session.context.length > 0
+                ? session.context[session.context.length - 1]
+                : undefined;
+            const contextSnapshot = createContextSnapshot(session.messages.length, new Date().toISOString(), previousContext);
+            session.context.push(contextSnapshot);
         }
         // Build ordered content blocks for the assistant response
         const contentBlocks = [];
@@ -187,12 +264,48 @@ export class AgentAcpAdapter {
             }
         };
         try {
+            // Execute hooks before agent invocation
+            const hooks = this.agent.definition.hooks;
+            logger.info("Checking hooks", {
+                noSession: this.noSession,
+                hasHooks: !!hooks,
+                hooksLength: hooks?.length ?? 0,
+                contextEntries: session.context.length,
+                totalMessages: session.messages.length,
+            });
+            if (!this.noSession && hooks && hooks.length > 0) {
+                logger.info("Executing hooks before agent invocation");
+                const hookExecutor = new HookExecutor(hooks, this.agent.definition.model, (callbackRef) => loadHookCallback(callbackRef, this.agentDir));
+                // Create read-only session view for hooks
+                const readonlySession = {
+                    messages: session.messages,
+                    context: session.context,
+                    requestParams: session.requestParams,
+                };
+                const hookResult = await hookExecutor.executeHooks(readonlySession);
+                // Send hook notifications to client
+                for (const notification of hookResult.notifications) {
+                    this.connection.sessionUpdate({
+                        sessionId: params.sessionId,
+                        update: notification,
+                    });
+                }
+                // Append new context entries returned by hooks
+                if (hookResult.newContextEntries.length > 0) {
+                    logger.info(`Appending ${hookResult.newContextEntries.length} new context entries from hooks`);
+                    session.context.push(...hookResult.newContextEntries);
+                }
+            }
+            // Resolve context to messages for agent invocation
+            const contextMessages = this.noSession
+                ? []
+                : resolveContextToMessages(session.context, session.messages);
             const invokeParams = {
                 prompt: params.prompt,
                 sessionId: params.sessionId,
                 messageId,
-                // Only pass session history if session persistence is enabled
-                sessionMessages: this.noSession ? [] : session.messages,
+                // Pass resolved context messages to agent
+                contextMessages,
             };
             // Only add sessionMeta if it's defined
             if (session.requestParams._meta) {
@@ -215,7 +328,7 @@ export class AgentAcpAdapter {
                         msg._meta &&
                         typeof msg._meta === "object" &&
                         "tokenUsage" in msg._meta) {
-                        console.log("DEBUG adapter: sending agent_message_chunk with tokenUsage in _meta:", JSON.stringify(msg._meta.tokenUsage));
+                        logger.debug("sending agent_message_chunk with tokenUsage in _meta", { tokenUsage: msg._meta.tokenUsage });
                     }
                 }
                 // Handle tool_call - flush pending text and add ToolCallBlock
@@ -299,14 +412,22 @@ export class AgentAcpAdapter {
                 timestamp: new Date().toISOString(),
             };
             session.messages.push(assistantMessage);
+            // Create context snapshot based on previous context
+            const previousContext = session.context.length > 0
+                ? session.context[session.context.length - 1]
+                : undefined;
+            const contextSnapshot = createContextSnapshot(session.messages.length, new Date().toISOString(), previousContext);
+            session.context.push(contextSnapshot);
         }
         // Save session to disk if storage is configured and session persistence is enabled
         if (!this.noSession && this.storage) {
             try {
-                await this.storage.saveSession(params.sessionId, session.messages);
+                await this.storage.saveSession(params.sessionId, session.messages, session.context);
             }
             catch (error) {
-                console.error(`Failed to save session ${params.sessionId}:`, error instanceof Error ? error.message : String(error));
+                logger.error(`Failed to save session ${params.sessionId}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
             }
         }
         session.pendingPrompt = null;

package/dist/acp-server/cli.d.ts

@@ -1,3 +1,5 @@
 import type { AgentDefinition } from "../definition";
 import { type AgentRunner } from "../runner";
-export declare function makeStdioTransport(agent: AgentRunner | AgentDefinition): void;
+export declare function makeStdioTransport(
+	agent: AgentRunner | AgentDefinition,
+): void;

package/dist/acp-server/session-storage.d.ts

@@ -26,6 +26,25 @@ export interface SessionMessage {
     content: ContentBlock[];
     timestamp: string;
 }
+/**
+ * Context entry types - for time-based context snapshots
+ */
+export interface MessagePointer {
+    type: "pointer";
+    index: number;
+}
+export interface FullMessageEntry {
+    type: "full";
+    message: SessionMessage;
+}
+export type ContextMessageEntry = MessagePointer | FullMessageEntry;
+/**
+ * Context entry - immutable snapshot of context at a point in time
+ */
+export interface ContextEntry {
+    timestamp: string;
+    messages: ContextMessageEntry[];
+}
 /**
  * Session metadata
  */
@@ -40,6 +59,7 @@ export interface SessionMetadata {
 export interface StoredSession {
     sessionId: string;
     messages: SessionMessage[];
+    context: ContextEntry[];
     metadata: SessionMetadata;
 }
 /**
@@ -67,7 +87,7 @@ export declare class SessionStorage {
      * Save a session to disk
      * Uses atomic write (write to temp file, then rename)
      */
-    saveSession(sessionId: string, messages: SessionMessage[]): Promise<void>;
+    saveSession(sessionId: string, messages: SessionMessage[], context: ContextEntry[]): Promise<void>;
     /**
      * Load a session from disk
      */

package/dist/acp-server/session-storage.js

@@ -40,6 +40,22 @@ const sessionMessageSchema = z.object({
     content: z.array(contentBlockSchema),
     timestamp: z.string(),
 });
+const messagePointerSchema = z.object({
+    type: z.literal("pointer"),
+    index: z.number(),
+});
+const fullMessageEntrySchema = z.object({
+    type: z.literal("full"),
+    message: sessionMessageSchema,
+});
+const contextMessageEntrySchema = z.discriminatedUnion("type", [
+    messagePointerSchema,
+    fullMessageEntrySchema,
+]);
+const contextEntrySchema = z.object({
+    timestamp: z.string(),
+    messages: z.array(contextMessageEntrySchema),
+});
 const sessionMetadataSchema = z.object({
     createdAt: z.string(),
     updatedAt: z.string(),
@@ -48,6 +64,7 @@ const sessionMetadataSchema = z.object({
 const storedSessionSchema = z.object({
     sessionId: z.string(),
     messages: z.array(sessionMessageSchema),
+    context: z.array(contextEntrySchema),
     metadata: sessionMetadataSchema,
 });
 /**
@@ -84,7 +101,7 @@ export class SessionStorage {
      * Save a session to disk
      * Uses atomic write (write to temp file, then rename)
      */
-    async saveSession(sessionId, messages) {
+    async saveSession(sessionId, messages, context) {
         this.ensureSessionsDir();
         const sessionPath = this.getSessionPath(sessionId);
         const tempPath = `${sessionPath}.tmp`;
@@ -95,6 +112,7 @@ export class SessionStorage {
         const session = {
             sessionId,
             messages,
+            context,
             metadata: {
                 createdAt: existingSession?.metadata.createdAt || now,
                 updatedAt: now,

package/dist/definition/index.d.ts

@@ -12,6 +12,16 @@ export declare const McpConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
     url: z.ZodString;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>]>;
+/** Hook configuration schema. */
+export declare const HookConfigSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        context_size: "context_size";
+    }>;
+    setting: z.ZodOptional<z.ZodObject<{
+        threshold: z.ZodNumber;
+    }, z.core.$strip>>;
+    callback: z.ZodString;
+}, z.core.$strip>;
 /** Agent definition schema. */
 export declare const AgentDefinitionSchema: z.ZodObject<{
     systemPrompt: z.ZodNullable<z.ZodString>;
@@ -43,4 +53,13 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>]>>>;
     harnessImplementation: z.ZodOptional<z.ZodLiteral<"langchain">>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            context_size: "context_size";
+        }>;
+        setting: z.ZodOptional<z.ZodObject<{
+            threshold: z.ZodNumber;
+        }, z.core.$strip>>;
+        callback: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;

package/dist/definition/index.js

@@ -52,6 +52,16 @@ const ToolSchema = z.union([
     FilesystemToolSchema,
     DirectToolSchema,
 ]);
+/** Hook configuration schema. */
+export const HookConfigSchema = z.object({
+    type: z.enum(["context_size"]),
+    setting: z
+        .object({
+        threshold: z.number().min(0).max(100),
+    })
+        .optional(),
+    callback: z.string(),
+});
 /** Agent definition schema. */
 export const AgentDefinitionSchema = z.object({
     systemPrompt: z.string().nullable(),
@@ -59,4 +69,5 @@ export const AgentDefinitionSchema = z.object({
     tools: z.array(ToolSchema).optional(),
     mcps: z.array(McpConfigSchema).optional(),
     harnessImplementation: z.literal("langchain").optional(),
+    hooks: z.array(HookConfigSchema).optional(),
 });

package/dist/definition/mcp.js

@@ -1 +0,0 @@
-"use strict";

package/dist/definition/tools/todo.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export declare const todoItemSchema: z.ZodObject<
+	{
+		content: z.ZodString;
+		status: z.ZodEnum<{
+			pending: "pending";
+			in_progress: "in_progress";
+			completed: "completed";
+		}>;
+		activeForm: z.ZodString;
+	},
+	z.core.$strip
+>;
+export declare const todoWrite: import("langchain").DynamicStructuredTool<
+	z.ZodObject<
+		{
+			todos: z.ZodArray<
+				z.ZodObject<
+					{
+						content: z.ZodString;
+						status: z.ZodEnum<{
+							pending: "pending";
+							in_progress: "in_progress";
+							completed: "completed";
+						}>;
+						activeForm: z.ZodString;
+					},
+					z.core.$strip
+				>
+			>;
+		},
+		z.core.$strip
+	>,
+	{
+		todos: {
+			content: string;
+			status: "pending" | "in_progress" | "completed";
+			activeForm: string;
+		}[];
+	},
+	{
+		todos: {
+			content: string;
+			status: "pending" | "in_progress" | "completed";
+			activeForm: string;
+		}[];
+	},
+	string
+>;

package/dist/definition/tools/todo.js

@@ -0,0 +1,80 @@
+import { tool } from "langchain";
+import { z } from "zod";
+export const todoItemSchema = z.object({
+	content: z.string().min(1),
+	status: z.enum(["pending", "in_progress", "completed"]),
+	activeForm: z.string().min(1),
+});
+export const todoWrite = tool(
+	({ todos }) => {
+		// Simple implementation that confirms the todos were written
+		return `Successfully updated todo list with ${todos.length} items`;
+	},
+	{
+		name: "todo_write",
+		description: `Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+3. User explicitly requests todo list - When the user directly asks you to use the todo list
+4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+5. After receiving new instructions - Immediately capture user requirements as todos
+6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
+7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking it provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task States and Management
+
+1. **Task States**: Use these states to track progress:
+   - pending: Task not yet started
+   - in_progress: Currently working on (limit to ONE task at a time)
+   - completed: Task finished successfully
+
+   **IMPORTANT**: Task descriptions must have two forms:
+   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")
+   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")
+
+2. **Task Management**:
+   - Update task status in real-time as you work
+   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+   - Exactly ONE task must be in_progress at any time (not less, not more)
+   - Complete current tasks before starting new ones
+   - Remove tasks that are no longer relevant from the list entirely
+
+3. **Task Completion Requirements**:
+   - ONLY mark a task as completed when you have FULLY accomplished it
+   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+   - When blocked, create a new task describing what needs to be resolved
+   - Never mark a task as completed if:
+     - Tests are failing
+     - Implementation is partial
+     - You encountered unresolved errors
+     - You couldn't find necessary files or dependencies
+
+4. **Task Breakdown**:
+   - Create specific, actionable items
+   - Break complex tasks into smaller, manageable steps
+   - Use clear, descriptive task names
+   - Always provide both forms:
+     - content: "Fix authentication bug"
+     - activeForm: "Fixing authentication bug"
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.`,
+		schema: z.object({
+			todos: z.array(todoItemSchema),
+		}),
+	},
+);

package/dist/definition/tools/web_search.d.ts

@@ -0,0 +1,4 @@
+import { ExaSearchResults } from "@langchain/exa";
+export declare function makeWebSearchTool(): ExaSearchResults<{
+	text: true;
+}>;

package/dist/definition/tools/web_search.js

@@ -0,0 +1,26 @@
+import { ExaSearchResults } from "@langchain/exa";
+import Exa from "exa-js";
+
+let _webSearchInstance = null;
+export function makeWebSearchTool() {
+	if (_webSearchInstance) {
+		return _webSearchInstance;
+	}
+	const apiKey = process.env.EXA_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"EXA_API_KEY environment variable is required to use the web_search tool. " +
+				"Please set it to your Exa API key from https://exa.ai",
+		);
+	}
+	const client = new Exa(apiKey);
+	_webSearchInstance = new ExaSearchResults({
+		client,
+		searchArgs: {
+			numResults: 5,
+			type: "auto",
+			text: true,
+		},
+	});
+	return _webSearchInstance;
+}

package/dist/dev-agent/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/dev-agent/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeHttpTransport, makeStdioTransport } from "../acp-server/index";
+// Load agent definition from JSON file
+const configPath = join(import.meta.dir, "agent.json");
+const agent = JSON.parse(readFileSync(configPath, "utf-8"));
+const transport = process.argv[2] || "stdio";
+if (transport === "http") {
+    makeHttpTransport(agent);
+}
+else if (transport === "stdio") {
+    makeStdioTransport(agent);
+}
+else {
+    console.error(`Invalid transport: ${transport}`);
+    process.exit(1);
+}

package/dist/example.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/example.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { makeHttpTransport, makeStdioTransport } from "./acp-server/index.js";
+
+const exampleAgent = {
+	model: "claude-sonnet-4-5-20250929",
+	systemPrompt: "You are a helpful assistant.",
+	tools: ["todo_write", "get_weather", "web_search"],
+};
+// Parse transport type from command line argument
+const transport = process.argv[2] || "stdio";
+if (transport === "http") {
+	makeHttpTransport(exampleAgent);
+} else if (transport === "stdio") {
+	makeStdioTransport(exampleAgent);
+} else {
+	console.error(`Invalid transport: ${transport}`);
+	console.error("Usage: bun run example.ts [stdio|http]");
+	process.exit(1);
+}

package/dist/index.js

@@ -1,6 +1,8 @@
 import { basename } from "node:path";
+import { createLogger } from "@townco/core";
 import { makeHttpTransport, makeStdioTransport } from "./acp-server";
 import { makeSubagentsTool } from "./utils";
+const logger = createLogger("agent-index");
 const exampleAgent = {
     model: "claude-sonnet-4-5-20250929",
     systemPrompt: "You are a helpful assistant.",
@@ -21,6 +23,15 @@ const exampleAgent = {
         ]),
     ],
     mcps: [],
+    hooks: [
+        {
+            type: "context_size",
+            setting: {
+                threshold: 95,
+            },
+            callback: "compaction_tool",
+        },
+    ],
 };
 // Parse transport type and flags from command line arguments
 const args = process.argv.slice(2);
@@ -40,7 +51,7 @@ else if (transport === "stdio") {
     makeStdioTransport(exampleAgent);
 }
 else {
-    console.error(`Invalid transport: ${transport}`);
-    console.error("Usage: bun run index.ts [stdio|http] [--no-session]");
+    logger.error(`Invalid transport: ${transport}`);
+    logger.error("Usage: bun run index.ts [stdio|http] [--no-session]");
     process.exit(1);
 }