@townco/agent 0.1.44 → 0.1.45

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

@@ -30,6 +30,15 @@ export declare const zAgentRunnerParams: z.ZodObject<{
         url: z.ZodString;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>]>>>;
+    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>;
 export type CreateAgentRunnerParams = z.infer<typeof zAgentRunnerParams>;
 export interface SessionMessage {
@@ -40,7 +49,7 @@ export interface SessionMessage {
 export type InvokeRequest = Omit<PromptRequest, "_meta"> & {
     messageId: string;
     sessionMeta?: Record<string, unknown>;
-    sessionMessages?: SessionMessage[];
+    contextMessages?: SessionMessage[];
 };
 export interface TokenUsage {
     inputTokens?: number;
@@ -58,6 +67,23 @@ export interface AgentMessageChunkWithTokens {
         [key: string]: unknown;
     };
 }
+export type HookNotificationUpdate = {
+    sessionUpdate: "hook_triggered";
+    hookType: string;
+    threshold: number;
+    currentPercentage: number;
+    callback: string;
+} | {
+    sessionUpdate: "hook_completed";
+    hookType: string;
+    callback: string;
+    metadata?: Record<string, unknown>;
+} | {
+    sessionUpdate: "hook_error";
+    hookType: string;
+    callback: string;
+    error: string;
+};
 export type ExtendedSessionUpdate = (SessionNotification["update"] & {
     prettyName?: string;
     icon?: string;
@@ -72,7 +98,7 @@ export type ExtendedSessionUpdate = (SessionNotification["update"] & {
     _meta?: {
         messageId?: string;
     };
-} | AgentMessageChunkWithTokens;
+} | AgentMessageChunkWithTokens | HookNotificationUpdate;
 /** Describes an object that can run an agent definition */
 export interface AgentRunner {
     definition: CreateAgentRunnerParams;

package/dist/runner/agent-runner.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
-import { McpConfigSchema } from "../definition";
+import { HookConfigSchema, McpConfigSchema } from "../definition";
 import { zToolType } from "./tools";
 export const zAgentRunnerParams = z.object({
     systemPrompt: z.string().nullable(),
     model: z.string(),
     tools: z.array(zToolType).optional(),
     mcps: z.array(McpConfigSchema).optional(),
+    hooks: z.array(HookConfigSchema).optional(),
 });

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

@@ -0,0 +1,9 @@
+/**
+ * Model context window sizes in tokens
+ * Add more models as needed
+ */
+export declare const MODEL_CONTEXT_WINDOWS: Record<string, number>;
+/**
+ * Default context size for unknown models
+ */
+export declare const DEFAULT_CONTEXT_SIZE = 200000;

package/dist/runner/hooks/constants.js

@@ -0,0 +1,19 @@
+/**
+ * Model context window sizes in tokens
+ * Add more models as needed
+ */
+export const MODEL_CONTEXT_WINDOWS = {
+    // Claude 3.5 Sonnet
+    "claude-sonnet-4-5-20250929": 200000,
+    "claude-sonnet-4-20250514": 200000,
+    "claude-3-5-sonnet-20241022": 200000,
+    "claude-3-5-sonnet-20240620": 200000,
+    // Claude 3 Opus
+    "claude-3-opus-20240229": 200000,
+    // Claude 3 Haiku
+    "claude-3-haiku-20240307": 200000,
+};
+/**
+ * Default context size for unknown models
+ */
+export const DEFAULT_CONTEXT_SIZE = 200000;

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

@@ -0,0 +1,23 @@
+import type { ContextEntry } from "../../acp-server/session-storage";
+import type { HookCallback, HookConfig, HookNotification, ReadonlySession } from "./types";
+/**
+ * Hook executor manages hook lifecycle
+ */
+export declare class HookExecutor {
+    private hooks;
+    private model;
+    private loadCallback;
+    constructor(hooks: HookConfig[], model: string, loadCallback: (callbackRef: string) => Promise<HookCallback>);
+    /**
+     * Execute hooks before agent invocation
+     * Returns new context entries to append and any notifications to send
+     */
+    executeHooks(session: ReadonlySession): Promise<{
+        newContextEntries: ContextEntry[];
+        notifications: HookNotification[];
+    }>;
+    /**
+     * Execute a context_size hook
+     */
+    private executeContextSizeHook;
+}

package/dist/runner/hooks/executor.js

@@ -0,0 +1,163 @@
+import { createLogger } from "@townco/core";
+import { DEFAULT_CONTEXT_SIZE, MODEL_CONTEXT_WINDOWS } from "./constants";
+const logger = createLogger("hook-executor");
+/**
+ * Get max context size for a model
+ */
+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
+ */
+export class HookExecutor {
+    hooks;
+    model;
+    loadCallback;
+    constructor(hooks, model, loadCallback) {
+        this.hooks = hooks;
+        this.model = model;
+        this.loadCallback = loadCallback;
+    }
+    /**
+     * Execute hooks before agent invocation
+     * Returns new context entries to append and any notifications to send
+     */
+    async executeHooks(session) {
+        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,
+        });
+        const newContextEntries = [];
+        const notifications = [];
+        for (const hook of this.hooks) {
+            if (hook.type === "context_size") {
+                const result = await this.executeContextSizeHook(hook, session);
+                if (result) {
+                    notifications.push(...result.notifications);
+                    if (result.newContextEntry) {
+                        newContextEntries.push(result.newContextEntry);
+                    }
+                }
+            }
+        }
+        return { newContextEntries, notifications };
+    }
+    /**
+     * Execute a context_size hook
+     */
+    async executeContextSizeHook(hook, session) {
+        // Resolve context to messages for token estimation
+        const resolvedMessages = resolveContextToMessages(session.context, session.messages);
+        const maxTokens = getModelMaxTokens(this.model);
+        const currentTokens = estimateTokens(resolvedMessages);
+        const percentage = (currentTokens / 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}%`);
+            return null; // No action needed
+        }
+        logger.info(`Context hook triggered: ${currentTokens} tokens (${percentage.toFixed(1)}%) exceeds threshold ${threshold}%`);
+        const notifications = [];
+        // Notify that hook is triggered
+        notifications.push({
+            type: "hook_triggered",
+            hookType: "context_size",
+            threshold,
+            currentPercentage: percentage,
+            callback: hook.callback,
+        });
+        try {
+            // Load and execute callback
+            const callback = await this.loadCallback(hook.callback);
+            const hookContext = {
+                session,
+                currentTokens,
+                maxTokens,
+                percentage,
+                model: this.model,
+            };
+            const result = await callback(hookContext);
+            // Notify completion
+            notifications.push({
+                type: "hook_completed",
+                hookType: "context_size",
+                callback: hook.callback,
+                metadata: result.metadata,
+            });
+            return {
+                newContextEntry: result.newContextEntry,
+                notifications,
+            };
+        }
+        catch (error) {
+            // Notify error
+            notifications.push({
+                type: "hook_error",
+                hookType: "context_size",
+                callback: hook.callback,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Return no context entry on error
+            return {
+                newContextEntry: null,
+                notifications,
+            };
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from "./constants";
+export * from "./executor";
+export * from "./loader";
+export * from "./registry";
+export * from "./types";

package/dist/runner/hooks/index.js

@@ -0,0 +1,5 @@
+export * from "./constants";
+export * from "./executor";
+export * from "./loader";
+export * from "./registry";
+export * from "./types";

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

@@ -0,0 +1,5 @@
+import type { HookCallback } from "./types";
+/**
+ * Load a hook callback from either registry or custom file
+ */
+export declare function loadHookCallback(callbackRef: string, agentDir?: string): Promise<HookCallback>;

package/dist/runner/hooks/loader.js

@@ -0,0 +1,49 @@
+import { resolve } from "node:path";
+import { createLogger } from "@townco/core";
+import { getPredefinedHook, isPredefinedHook } from "./registry";
+const logger = createLogger("hook-loader");
+/**
+ * Load a hook callback from either registry or custom file
+ */
+export async function loadHookCallback(callbackRef, agentDir) {
+    // Check if it's a predefined hook
+    if (isPredefinedHook(callbackRef)) {
+        const hook = getPredefinedHook(callbackRef);
+        if (!hook) {
+            throw new Error(`Predefined hook "${callbackRef}" not found`);
+        }
+        return hook;
+    }
+    // It's a file path - load custom hook
+    if (!agentDir) {
+        throw new Error(`Cannot load custom hook "${callbackRef}" without agent directory`);
+    }
+    try {
+        // Resolve path relative to agent directory
+        const hookPath = resolve(agentDir, callbackRef);
+        logger.debug(`Loading custom hook from ${hookPath}`);
+        // Dynamic import the module
+        const module = await import(hookPath);
+        // Type guard to check if module is an object
+        if (typeof module !== "object" || module === null) {
+            throw new Error(`Hook module at "${hookPath}" must export an object`);
+        }
+        // Look for default export or named export
+        const moduleObj = module;
+        const callback = moduleObj.default || moduleObj.hookCallback || moduleObj.callback;
+        if (!callback) {
+            throw new Error(`Hook module at "${hookPath}" must export a default function or "hookCallback"`);
+        }
+        if (typeof callback !== "function") {
+            throw new Error(`Hook at "${hookPath}" must export a function, got ${typeof callback}`);
+        }
+        return callback;
+    }
+    catch (error) {
+        const errorData = typeof error === "object" && error !== null
+            ? error
+            : undefined;
+        logger.error(`Failed to load custom hook "${callbackRef}"`, errorData);
+        throw new Error(`Failed to load custom hook "${callbackRef}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/runner/hooks/predefined/compaction-tool.d.ts

@@ -0,0 +1,6 @@
+import { type HookCallback } from "../types";
+/**
+ * Placeholder compaction tool for testing hooks
+ * Logs the context and returns null (no new context entry)
+ */
+export declare const compactionTool: HookCallback;

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

@@ -0,0 +1,42 @@
+import { createLogger } from "@townco/core";
+import { createContextEntry, createFullMessageEntry, } from "../types";
+const logger = createLogger("compaction-tool");
+/**
+ * Placeholder compaction tool for testing hooks
+ * Logs the context and returns null (no new context entry)
+ */
+export const compactionTool = async (ctx) => {
+    logger.info("Compaction tool triggered", {
+        currentTokens: ctx.currentTokens,
+        maxTokens: ctx.maxTokens,
+        percentage: ctx.percentage.toFixed(2) + "%",
+        contextEntries: ctx.session.context.length,
+        totalMessages: ctx.session.messages.length,
+        model: ctx.model,
+    });
+    // TODO: Implement actual compaction logic
+    // Example: Create a new context entry with a summary message
+    // const summaryEntry = createFullMessageEntry(
+    //   "assistant",
+    //   "Summary of previous conversation: ..."
+    // );
+    //
+    // const newContextEntry = createContextEntry([summaryEntry]);
+    //
+    // return {
+    //   newContextEntry,
+    //   metadata: {
+    //     action: "compacted",
+    //     messagesRemoved: ctx.session.messages.length - 1,
+    //     tokensSaved: 1000,
+    //   },
+    // };
+    // For now, just return null (no new context entry)
+    return {
+        newContextEntry: null,
+        metadata: {
+            action: "placeholder",
+            message: "Compaction tool called but no action taken (placeholder)",
+        },
+    };
+};

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

@@ -0,0 +1,14 @@
+import type { HookCallback } from "./types";
+/**
+ * Registry of predefined hook callbacks
+ * Maps callback names to their implementations
+ */
+export declare const HOOK_REGISTRY: Record<string, HookCallback>;
+/**
+ * Check if a callback name is a predefined hook
+ */
+export declare function isPredefinedHook(callback: string): boolean;
+/**
+ * Get a predefined hook callback by name
+ */
+export declare function getPredefinedHook(callback: string): HookCallback | undefined;

package/dist/runner/hooks/registry.js

@@ -0,0 +1,20 @@
+import { compactionTool } from "./predefined/compaction-tool";
+/**
+ * Registry of predefined hook callbacks
+ * Maps callback names to their implementations
+ */
+export const HOOK_REGISTRY = {
+    compaction_tool: compactionTool,
+};
+/**
+ * Check if a callback name is a predefined hook
+ */
+export function isPredefinedHook(callback) {
+    return callback in HOOK_REGISTRY;
+}
+/**
+ * Get a predefined hook callback by name
+ */
+export function getPredefinedHook(callback) {
+    return HOOK_REGISTRY[callback];
+}

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

@@ -0,0 +1,144 @@
+import type { ContextEntry } from "../../acp-server/session-storage";
+import type { SessionMessage } from "../agent-runner";
+/**
+ * Hook types supported by the agent system
+ */
+export type HookType = "context_size";
+/**
+ * Settings for context_size hook
+ */
+export interface ContextSizeSettings {
+    /**
+     * Threshold as percentage (0-100) of model's max context window
+     */
+    threshold: number;
+}
+/**
+ * Hook configuration in agent definition
+ */
+export interface HookConfig {
+    /**
+     * Type of hook to trigger
+     */
+    type: HookType;
+    /**
+     * Optional hook-specific settings
+     */
+    setting?: ContextSizeSettings | undefined;
+    /**
+     * Callback reference - either a predefined hook name or a file path
+     * Examples: "compaction_tool" or "./hooks/my_compaction_tool.ts"
+     */
+    callback: string;
+}
+/**
+ * Read-only view of an agent session for hooks
+ */
+export interface ReadonlySession {
+    /**
+     * All session messages
+     */
+    readonly messages: ReadonlyArray<Readonly<SessionMessage>>;
+    /**
+     * Current context entries (time-based snapshots)
+     */
+    readonly context: ReadonlyArray<Readonly<ContextEntry>>;
+    /**
+     * Original request parameters
+     */
+    readonly requestParams: Readonly<Record<string, unknown>>;
+}
+/**
+ * Context passed to hook callbacks
+ */
+export interface HookContext {
+    /**
+     * Read-only access to the full session
+     */
+    session: ReadonlySession;
+    /**
+     * Current context size in tokens
+     */
+    currentTokens: number;
+    /**
+     * Maximum context size for the model in tokens
+     */
+    maxTokens: number;
+    /**
+     * Percentage of context used (0-100)
+     */
+    percentage: number;
+    /**
+     * The model being used
+     */
+    model: string;
+}
+/**
+ * Result returned by hook callbacks
+ */
+export interface HookResult {
+    /**
+     * New context entry to append to session.context
+     * If null, no context change is made
+     */
+    newContextEntry: ContextEntry | null;
+    /**
+     * Optional metadata about what the hook did
+     */
+    metadata?: {
+        action?: string;
+        messagesRemoved?: number;
+        tokensSaved?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Hook callback function signature
+ */
+export type HookCallback = (context: HookContext) => Promise<HookResult>;
+/**
+ * Helper function to create a new context entry
+ * Use this when hooks want to create a new context snapshot
+ */
+export declare function createContextEntry(messages: Array<{
+    type: "pointer";
+    index: number;
+} | {
+    type: "full";
+    message: SessionMessage;
+}>, timestamp?: string): ContextEntry;
+/**
+ * Helper function to create a full message entry for context
+ * Use this when hooks need to inject new messages into context
+ */
+export declare function createFullMessageEntry(role: "user" | "assistant", text: string): {
+    type: "full";
+    message: SessionMessage;
+};
+/**
+ * Helper function to create a pointer entry for context
+ */
+export declare function createPointerEntry(index: number): {
+    type: "pointer";
+    index: number;
+};
+/**
+ * Hook notification events for GUI/TUI
+ */
+export type HookNotification = {
+    type: "hook_triggered";
+    hookType: HookType;
+    threshold: number;
+    currentPercentage: number;
+    callback: string;
+} | {
+    type: "hook_completed";
+    hookType: HookType;
+    callback: string;
+    metadata?: HookResult["metadata"];
+} | {
+    type: "hook_error";
+    hookType: HookType;
+    callback: string;
+    error: string;
+};

package/dist/runner/hooks/types.js

@@ -0,0 +1,33 @@
+/**
+ * Helper function to create a new context entry
+ * Use this when hooks want to create a new context snapshot
+ */
+export function createContextEntry(messages, timestamp) {
+    return {
+        timestamp: timestamp || new Date().toISOString(),
+        messages,
+    };
+}
+/**
+ * Helper function to create a full message entry for context
+ * Use this when hooks need to inject new messages into context
+ */
+export function createFullMessageEntry(role, text) {
+    return {
+        type: "full",
+        message: {
+            role,
+            content: [{ type: "text", text }],
+            timestamp: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Helper function to create a pointer entry for context
+ */
+export function createPointerEntry(index) {
+    return {
+        type: "pointer",
+        index,
+    };
+}

package/dist/runner/index.d.ts

@@ -1,4 +1,6 @@
 import type { AgentDefinition } from "../definition";
 import { type AgentRunner } from "./agent-runner";
 export type { AgentRunner };
-export declare const makeRunnerFromDefinition: (definition: AgentDefinition) => AgentRunner;
+export declare const makeRunnerFromDefinition: (
+	definition: AgentDefinition,
+) => AgentRunner;