@townco/agent 0.1.49 → 0.1.51

package/dist/acp-server/http.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { gzipSync } from "node:zlib";
 import * as acp from "@agentclientprotocol/sdk";
 import { PGlite } from "@electric-sql/pglite";
-import { createLogger } from "@townco/core";
+import { configureLogsDir, createLogger } from "@townco/core";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { streamSSE } from "hono/streaming";
@@ -48,6 +49,12 @@ function safeChannelName(prefix, id) {
     return `${prefix}_${hash}`;
 }
 export function makeHttpTransport(agent, agentDir, agentName) {
+    // Configure logger to write to .logs/ directory if agentDir is provided
+    if (agentDir) {
+        const logsDir = join(agentDir, ".logs");
+        configureLogsDir(logsDir);
+        logger.info("Configured logs directory", { logsDir });
+    }
     const inbound = new TransformStream();
     const outbound = new TransformStream();
     const bridge = acp.ndJsonStream(outbound.writable, inbound.readable);

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

@@ -16,6 +16,12 @@ export interface ToolCallBlock {
     error?: string | undefined;
     startedAt?: number | undefined;
     completedAt?: number | undefined;
+    _meta?: {
+        truncationWarning?: string;
+        compactionAction?: "compacted" | "truncated";
+        originalTokens?: number;
+        finalTokens?: number;
+    };
 }
 export type ContentBlock = TextBlock | ToolCallBlock;
 /**
@@ -50,6 +56,19 @@ export interface ContextEntry {
      * compacted into the full message(s) in this entry
      */
     compactedUpTo?: number | undefined;
+    /**
+     * Complete breakdown of context size at this snapshot.
+     * Calculated by counting ALL tokens in the messages referenced by this context entry.
+     */
+    context_size: {
+        systemPromptTokens: number;
+        userMessagesTokens: number;
+        assistantMessagesTokens: number;
+        toolInputTokens: number;
+        toolResultsTokens: number;
+        totalEstimated: number;
+        llmReportedInputTokens?: number | undefined;
+    };
 }
 /**
  * Session metadata

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

@@ -56,6 +56,15 @@ const contextEntrySchema = z.object({
     timestamp: z.string(),
     messages: z.array(contextMessageEntrySchema),
     compactedUpTo: z.number().optional(),
+    context_size: z.object({
+        systemPromptTokens: z.number(),
+        userMessagesTokens: z.number(),
+        assistantMessagesTokens: z.number(),
+        toolInputTokens: z.number(),
+        toolResultsTokens: z.number(),
+        totalEstimated: z.number(),
+        llmReportedInputTokens: z.number().optional(),
+    }),
 });
 const sessionMetadataSchema = z.object({
     createdAt: z.string(),

package/dist/definition/index.d.ts

@@ -16,14 +16,22 @@ export declare const McpConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
 export declare const HookConfigSchema: z.ZodObject<{
     type: z.ZodEnum<{
         context_size: "context_size";
+        tool_response: "tool_response";
     }>;
-    setting: z.ZodOptional<z.ZodObject<{
+    setting: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         threshold: z.ZodNumber;
-    }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        maxContextThreshold: z.ZodOptional<z.ZodNumber>;
+        responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
     callback: z.ZodString;
 }, z.core.$strip>;
 /** Agent definition schema. */
 export declare const AgentDefinitionSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    suggestedPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     systemPrompt: z.ZodNullable<z.ZodString>;
     model: z.ZodString;
     tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -56,10 +64,14 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
     hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
             context_size: "context_size";
+            tool_response: "tool_response";
         }>;
-        setting: z.ZodOptional<z.ZodObject<{
+        setting: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             threshold: z.ZodNumber;
-        }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            maxContextThreshold: z.ZodOptional<z.ZodNumber>;
+            responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;

package/dist/definition/index.js

@@ -54,16 +54,29 @@ const ToolSchema = z.union([
 ]);
 /** Hook configuration schema. */
 export const HookConfigSchema = z.object({
-    type: z.enum(["context_size"]),
+    type: z.enum(["context_size", "tool_response"]),
     setting: z
-        .object({
-        threshold: z.number().min(0).max(100),
-    })
+        .union([
+        // For context_size hooks
+        z.object({
+            threshold: z.number().min(0).max(100),
+        }),
+        // For tool_response hooks
+        z.object({
+            maxContextThreshold: z.number().min(0).max(100).optional(),
+            responseTruncationThreshold: z.number().min(0).max(100).optional(),
+        }),
+    ])
         .optional(),
     callback: z.string(),
 });
 /** Agent definition schema. */
 export const AgentDefinitionSchema = z.object({
+    /** Human-readable display name for the agent (shown in UI). */
+    displayName: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    suggestedPrompts: z.array(z.string()).optional(),
     systemPrompt: z.string().nullable(),
     model: z.string(),
     tools: z.array(ToolSchema).optional(),

package/dist/index.d.ts

@@ -1 +1,2 @@
-export {};
+export { configureTelemetry, type TelemetryConfig } from "./telemetry/index.js";
+export { initializeOpenTelemetry, initializeOpenTelemetryFromEnv, type TelemetrySetupOptions, } from "./telemetry/setup.js";

package/dist/index.js

@@ -1,7 +1,16 @@
 import { basename } from "node:path";
 import { createLogger } from "@townco/core";
 import { makeHttpTransport, makeStdioTransport } from "./acp-server";
+import { initializeOpenTelemetryFromEnv } from "./telemetry/setup.js";
 import { makeSubagentsTool } from "./utils";
+// Re-export telemetry configuration for library users
+export { configureTelemetry } from "./telemetry/index.js";
+export { initializeOpenTelemetry, initializeOpenTelemetryFromEnv, } from "./telemetry/setup.js";
+// Configure OpenTelemetry if enabled via environment variable
+// Example: ENABLE_TELEMETRY=true bun run index.ts stdio
+if (process.env.ENABLE_TELEMETRY === "true") {
+    initializeOpenTelemetryFromEnv();
+}
 const logger = createLogger("agent-index");
 const exampleAgent = {
     model: "claude-sonnet-4-5-20250929",
@@ -27,7 +36,7 @@ const exampleAgent = {
         {
             type: "context_size",
             setting: {
-                threshold: 95,
+                threshold: 80,
             },
             callback: "compaction_tool",
         },

package/dist/runner/agent-runner.d.ts

@@ -2,6 +2,10 @@ import type { PromptRequest, PromptResponse, SessionNotification } from "@agentc
 import { z } from "zod";
 import type { ContentBlock } from "../acp-server/session-storage.js";
 export declare const zAgentRunnerParams: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    suggestedPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     systemPrompt: z.ZodNullable<z.ZodString>;
     model: z.ZodString;
     tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"todo_write">, z.ZodLiteral<"get_weather">, z.ZodLiteral<"web_search">, z.ZodLiteral<"filesystem">]>, z.ZodObject<{
@@ -33,10 +37,14 @@ export declare const zAgentRunnerParams: z.ZodObject<{
     hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
             context_size: "context_size";
+            tool_response: "tool_response";
         }>;
-        setting: z.ZodOptional<z.ZodObject<{
+        setting: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             threshold: z.ZodNumber;
-        }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            maxContextThreshold: z.ZodOptional<z.ZodNumber>;
+            responseTruncationThreshold: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -64,6 +72,7 @@ export interface AgentMessageChunkWithTokens {
     };
     _meta?: {
         tokenUsage?: TokenUsage;
+        contextInputTokens?: number;
         [key: string]: unknown;
     };
 }
@@ -97,6 +106,8 @@ export type ExtendedSessionUpdate = (SessionNotification["update"] & {
     rawOutput?: Record<string, unknown>;
     _meta?: {
         messageId?: string;
+        contextInputTokens?: number;
+        [key: string]: unknown;
     };
 } | AgentMessageChunkWithTokens | HookNotificationUpdate;
 /** Describes an object that can run an agent definition */

package/dist/runner/agent-runner.js

@@ -2,6 +2,10 @@ import { z } from "zod";
 import { HookConfigSchema, McpConfigSchema } from "../definition";
 import { zToolType } from "./tools";
 export const zAgentRunnerParams = z.object({
+    displayName: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    suggestedPrompts: z.array(z.string()).optional(),
     systemPrompt: z.string().nullable(),
     model: z.string(),
     tools: z.array(zToolType).optional(),

package/dist/runner/hooks/executor.d.ts

@@ -12,7 +12,7 @@ export declare class HookExecutor {
      * Execute hooks before agent invocation
      * Returns new context entries to append and any notifications to send
      */
-    executeHooks(session: ReadonlySession): Promise<{
+    executeHooks(session: ReadonlySession, actualInputTokens: number): Promise<{
         newContextEntries: ContextEntry[];
         notifications: HookNotification[];
     }>;
@@ -20,4 +20,21 @@ export declare class HookExecutor {
      * Execute a context_size hook
      */
     private executeContextSizeHook;
+    /**
+     * Execute tool_response hooks when a tool returns output
+     */
+    executeToolResponseHooks(session: ReadonlySession, currentContextTokens: number, toolResponse: {
+        toolCallId: string;
+        toolName: string;
+        toolInput: Record<string, unknown>;
+        rawOutput: Record<string, unknown>;
+        outputTokens: number;
+    }): Promise<{
+        modifiedOutput?: Record<string, unknown>;
+        truncationWarning?: string;
+    }>;
+    /**
+     * Execute a single tool_response hook
+     */
+    private executeToolResponseHook;
 }

package/dist/runner/hooks/executor.js

@@ -7,58 +7,6 @@ const logger = createLogger("hook-executor");
 function getModelMaxTokens(model) {
     return MODEL_CONTEXT_WINDOWS[model] ?? DEFAULT_CONTEXT_SIZE;
 }
-/**
- * Estimate token count for session messages
- * This is a rough estimate: ~4 characters per token
- */
-function estimateTokens(messages) {
-    let totalChars = 0;
-    for (const message of messages) {
-        // Count characters in content blocks
-        for (const block of message.content) {
-            if (block.type === "text") {
-                totalChars += block.text.length;
-            }
-            else if (block.type === "tool_call") {
-                // Estimate tool call size (title + inputs/outputs)
-                totalChars += block.title.length;
-                if (block.rawInput) {
-                    totalChars += JSON.stringify(block.rawInput).length;
-                }
-                if (block.rawOutput) {
-                    totalChars += JSON.stringify(block.rawOutput).length;
-                }
-            }
-        }
-    }
-    // Rough estimate: 4 characters per token
-    return Math.ceil(totalChars / 4);
-}
-/**
- * Resolve context entries to session messages
- */
-function resolveContextToMessages(context, allMessages) {
-    if (context.length === 0) {
-        return [];
-    }
-    const latestContext = context[context.length - 1];
-    if (!latestContext) {
-        return [];
-    }
-    const resolved = [];
-    for (const entry of latestContext.messages) {
-        if (entry.type === "pointer") {
-            const message = allMessages[entry.index];
-            if (message) {
-                resolved.push(message);
-            }
-        }
-        else if (entry.type === "full") {
-            resolved.push(entry.message);
-        }
-    }
-    return resolved;
-}
 /**
  * Hook executor manages hook lifecycle
  */
@@ -75,17 +23,18 @@ export class HookExecutor {
      * Execute hooks before agent invocation
      * Returns new context entries to append and any notifications to send
      */
-    async executeHooks(session) {
+    async executeHooks(session, actualInputTokens) {
         logger.info(`Executing hooks - found ${this.hooks.length} hook(s)`, {
             hooks: this.hooks.map((h) => h.type),
             contextEntries: session.context.length,
             totalMessages: session.messages.length,
+            actualInputTokens,
         });
         const newContextEntries = [];
         const notifications = [];
         for (const hook of this.hooks) {
             if (hook.type === "context_size") {
-                const result = await this.executeContextSizeHook(hook, session);
+                const result = await this.executeContextSizeHook(hook, session, actualInputTokens);
                 if (result) {
                     notifications.push(...result.notifications);
                     if (result.newContextEntry) {
@@ -99,20 +48,17 @@ export class HookExecutor {
     /**
      * Execute a context_size hook
      */
-    async executeContextSizeHook(hook, session) {
-        // Resolve context to messages for token estimation
-        const resolvedMessages = resolveContextToMessages(session.context, session.messages);
+    async executeContextSizeHook(hook, session, actualInputTokens) {
         const maxTokens = getModelMaxTokens(this.model);
-        const currentTokens = estimateTokens(resolvedMessages);
-        const percentage = (currentTokens / maxTokens) * 100;
+        const percentage = (actualInputTokens / maxTokens) * 100;
         // Default threshold is 95%
         const threshold = hook.setting?.threshold ?? 95;
         // Check if threshold exceeded
         if (percentage < threshold) {
-            logger.info(`Context hook not triggered: ${currentTokens} tokens (${percentage.toFixed(1)}%) < threshold ${threshold}%`);
+            logger.info(`Context hook not triggered: ${actualInputTokens} tokens (${percentage.toFixed(1)}%) < threshold ${threshold}%`);
             return null; // No action needed
         }
-        logger.info(`Context hook triggered: ${currentTokens} tokens (${percentage.toFixed(1)}%) exceeds threshold ${threshold}%`);
+        logger.info(`Context hook triggered: ${actualInputTokens} tokens (${percentage.toFixed(1)}%) exceeds threshold ${threshold}%`);
         const notifications = [];
         // Notify that hook is triggered
         notifications.push({
@@ -127,7 +73,7 @@ export class HookExecutor {
             const callback = await this.loadCallback(hook.callback);
             const hookContext = {
                 session,
-                currentTokens,
+                currentTokens: actualInputTokens,
                 maxTokens,
                 percentage,
                 model: this.model,
@@ -160,4 +106,70 @@ export class HookExecutor {
             };
         }
     }
+    /**
+     * Execute tool_response hooks when a tool returns output
+     */
+    async executeToolResponseHooks(session, currentContextTokens, toolResponse) {
+        logger.info(`Executing tool_response hooks - found ${this.hooks.length} hook(s)`, {
+            toolCallId: toolResponse.toolCallId,
+            toolName: toolResponse.toolName,
+            outputTokens: toolResponse.outputTokens,
+        });
+        for (const hook of this.hooks) {
+            if (hook.type === "tool_response") {
+                const result = await this.executeToolResponseHook(hook, session, currentContextTokens, toolResponse);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+        return {}; // No modifications
+    }
+    /**
+     * Execute a single tool_response hook
+     */
+    async executeToolResponseHook(hook, session, currentContextTokens, toolResponse) {
+        const maxTokens = getModelMaxTokens(this.model);
+        try {
+            // Load and execute callback
+            const callback = await this.loadCallback(hook.callback);
+            // Pass hook settings through requestParams
+            const sessionWithSettings = {
+                ...session,
+                requestParams: {
+                    ...session.requestParams,
+                    hookSettings: hook.setting,
+                },
+            };
+            const hookContext = {
+                session: sessionWithSettings,
+                currentTokens: currentContextTokens,
+                maxTokens,
+                percentage: (currentContextTokens / maxTokens) * 100,
+                model: this.model,
+                toolResponse,
+            };
+            const result = await callback(hookContext);
+            // Extract modified output and warnings from metadata
+            if (result.metadata) {
+                const response = {};
+                if (result.metadata.modifiedOutput) {
+                    response.modifiedOutput = result.metadata.modifiedOutput;
+                }
+                if (result.metadata.truncationWarning) {
+                    response.truncationWarning = result.metadata
+                        .truncationWarning;
+                }
+                return response;
+            }
+            return null;
+        }
+        catch (error) {
+            logger.error("Tool response hook execution failed", {
+                callback: hook.callback,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null; // Return original output on error
+        }
+    }
 }

package/dist/runner/hooks/predefined/compaction-tool.js

@@ -84,22 +84,38 @@ Please provide your summary based on the conversation above, following this stru
                     .map((block) => block.text)
                     .join("\n")
                 : "Failed to extract summary";
+        // Extract token usage from LLM response
+        const responseUsage = response.usage_metadata;
+        const summaryTokens = responseUsage?.output_tokens ?? 0;
+        const inputTokensUsed = responseUsage?.input_tokens ?? ctx.currentTokens;
         logger.info("Generated compaction summary", {
             originalMessages: messagesToCompact.length,
             summaryLength: summaryText.length,
-            estimatedTokensSaved: Math.round(ctx.currentTokens * 0.7),
+            inputTokens: inputTokensUsed,
+            summaryTokens,
+            tokensSaved: inputTokensUsed - summaryTokens,
         });
         // Create a new context entry with the summary
         const summaryEntry = createFullMessageEntry("user", `This session is being continued from a previous conversation that ran out of context. The conversation is summarized below:\n${summaryText}`);
         // Set compactedUpTo to indicate all messages have been compacted into the summary
         const lastMessageIndex = messagesToCompact.length - 1;
-        const newContextEntry = createContextEntry([summaryEntry], undefined, lastMessageIndex);
+        const newContextEntry = createContextEntry([summaryEntry], undefined, lastMessageIndex, {
+            // Store summary tokens in userMessagesTokens since the summary is a user message
+            systemPromptTokens: 0,
+            userMessagesTokens: summaryTokens,
+            assistantMessagesTokens: 0,
+            toolInputTokens: 0,
+            toolResultsTokens: 0,
+            totalEstimated: summaryTokens,
+        });
         return {
             newContextEntry,
             metadata: {
                 action: "compacted",
                 messagesRemoved: messagesToCompact.length - 1,
-                tokensSaved: Math.round(ctx.currentTokens * 0.7),
+                tokensBeforeCompaction: inputTokensUsed,
+                tokensSaved: inputTokensUsed - summaryTokens,
+                summaryTokens, // Token count of the summary itself
                 summaryGenerated: true,
             },
         };

package/dist/runner/hooks/predefined/tool-response-compactor.d.ts

@@ -0,0 +1,6 @@
+import type { HookCallback } from "../types.js";
+/**
+ * Tool response compaction hook - compacts or truncates large tool responses
+ * to prevent context overflow
+ */
+export declare const toolResponseCompactor: HookCallback;