@townco/agent 0.1.55 → 0.1.57

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

@@ -24,6 +24,8 @@ export declare class AgentAcpAdapter implements acp.Agent {
     private agentVersion;
     private agentDescription;
     private agentSuggestedPrompts;
+    private agentInitialMessage;
+    private agentUiConfig;
     private currentToolOverheadTokens;
     private currentMcpOverheadTokens;
     constructor(agent: AgentRunner, connection: acp.AgentSideConnection, agentDir?: string, agentName?: string);
@@ -48,6 +50,11 @@ export declare class AgentAcpAdapter implements acp.Agent {
     private saveSessionToDisk;
     initialize(_params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
     newSession(params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;
+    /**
+     * Store an initial message in the session.
+     * Called by the HTTP transport after sending the initial message via SSE.
+     */
+    storeInitialMessage(sessionId: string, content: string): Promise<void>;
     loadSession(params: acp.LoadSessionRequest): Promise<acp.LoadSessionResponse>;
     authenticate(_params: acp.AuthenticateRequest): Promise<acp.AuthenticateResponse | undefined>;
     setSessionMode(_params: acp.SetSessionModeRequest): Promise<acp.SetSessionModeResponse>;

package/dist/acp-server/adapter.js

@@ -105,6 +105,8 @@ export class AgentAcpAdapter {
     agentVersion;
     agentDescription;
     agentSuggestedPrompts;
+    agentInitialMessage;
+    agentUiConfig;
     currentToolOverheadTokens = 0; // Track tool overhead for current turn
     currentMcpOverheadTokens = 0; // Track MCP overhead for current turn
     constructor(agent, connection, agentDir, agentName) {
@@ -117,6 +119,8 @@ export class AgentAcpAdapter {
         this.agentVersion = agent.definition.version;
         this.agentDescription = agent.definition.description;
         this.agentSuggestedPrompts = agent.definition.suggestedPrompts;
+        this.agentInitialMessage = agent.definition.initialMessage;
+        this.agentUiConfig = agent.definition.uiConfig;
         this.noSession = process.env.TOWN_NO_SESSION === "true";
         this.storage =
             agentDir && agentName && !this.noSession
@@ -129,6 +133,7 @@ export class AgentAcpAdapter {
             agentVersion: this.agentVersion,
             agentDescription: this.agentDescription,
             suggestedPrompts: this.agentSuggestedPrompts,
+            initialMessage: this.agentInitialMessage,
             noSession: this.noSession,
             hasStorage: this.storage !== null,
             sessionStoragePath: this.storage ? `${agentDir}/.sessions` : null,
@@ -259,6 +264,10 @@ export class AgentAcpAdapter {
             ...(this.agentSuggestedPrompts
                 ? { suggestedPrompts: this.agentSuggestedPrompts }
                 : {}),
+            ...(this.agentInitialMessage
+                ? { initialMessage: this.agentInitialMessage }
+                : {}),
+            ...(this.agentUiConfig ? { uiConfig: this.agentUiConfig } : {}),
             ...(toolsMetadata.length > 0 ? { tools: toolsMetadata } : {}),
             ...(mcpsMetadata.length > 0 ? { mcps: mcpsMetadata } : {}),
             ...(subagentsMetadata.length > 0 ? { subagents: subagentsMetadata } : {}),
@@ -273,10 +282,38 @@ export class AgentAcpAdapter {
             context: [],
             requestParams: params,
         });
+        // Note: Initial message is sent by the HTTP transport when SSE connection is established
+        // This ensures the message is delivered after the client is ready to receive it
         return {
             sessionId,
         };
     }
+    /**
+     * Store an initial message in the session.
+     * Called by the HTTP transport after sending the initial message via SSE.
+     */
+    async storeInitialMessage(sessionId, content) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            logger.warn("Cannot store initial message - session not found", {
+                sessionId,
+            });
+            return;
+        }
+        // Add the initial message as an assistant message
+        const initialMessage = {
+            role: "assistant",
+            content: [{ type: "text", text: content }],
+            timestamp: new Date().toISOString(),
+        };
+        session.messages.push(initialMessage);
+        // Save to disk if session persistence is enabled
+        await this.saveSessionToDisk(sessionId, session);
+        logger.debug("Stored initial message in session", {
+            sessionId,
+            contentPreview: content.slice(0, 100),
+        });
+    }
     async loadSession(params) {
         if (!this.storage) {
             throw new Error("Session storage is not configured");
@@ -510,13 +547,11 @@ export class AgentAcpAdapter {
                 ? session.context[session.context.length - 1]
                 : undefined;
             // Calculate context size for this snapshot
-            // Build message pointers for the new context (previous messages + new user message)
+            // Build message pointers for the new context (previous messages only, NOT the new user message)
+            // The new user message will be passed separately via the prompt parameter
             const messageEntries = previousContext
-                ? [
-                    ...previousContext.messages,
-                    { type: "pointer", index: session.messages.length - 1 },
-                ]
-                : [{ type: "pointer", index: 0 }];
+                ? [...previousContext.messages]
+                : [];
             // Resolve message entries to actual messages
             const contextMessages = [];
             for (const entry of messageEntries) {
@@ -741,6 +776,23 @@ export class AgentAcpAdapter {
                             toolCallBlock.completedAt = Date.now();
                         }
                     }
+                    // Forward tool_call_update with _meta to the client (for subagent connection info, etc.)
+                    if (updateMsg._meta) {
+                        logger.info("Forwarding tool_call_update with _meta to client", {
+                            toolCallId: updateMsg.toolCallId,
+                            status: updateMsg.status,
+                            _meta: updateMsg._meta,
+                        });
+                        this.connection.sessionUpdate({
+                            sessionId: params.sessionId,
+                            update: {
+                                sessionUpdate: "tool_call_update",
+                                toolCallId: updateMsg.toolCallId,
+                                status: updateMsg.status,
+                                _meta: updateMsg._meta,
+                            },
+                        });
+                    }
                 }
                 // Handle tool_output - update ToolCallBlock with output content
                 if ("sessionUpdate" in msg && msg.sessionUpdate === "tool_output") {
@@ -808,33 +860,53 @@ export class AgentAcpAdapter {
                             // Check if we already have a partial assistant message in messages
                             const lastMessage = session.messages[session.messages.length - 1];
                             let partialMessageIndex;
+                            let userMessageIndex;
+                            let isFirstToolInTurn;
                             if (lastMessage && lastMessage.role === "assistant") {
-                                // Update existing partial message
+                                // Update existing partial message (subsequent tool in same turn)
                                 session.messages[session.messages.length - 1] =
                                     partialAssistantMessage;
                                 partialMessageIndex = session.messages.length - 1;
+                                userMessageIndex = session.messages.length - 2;
+                                isFirstToolInTurn = false;
                             }
                             else {
-                                // Add new partial message
+                                // Add new partial message (first tool in this turn)
                                 session.messages.push(partialAssistantMessage);
                                 partialMessageIndex = session.messages.length - 1;
+                                userMessageIndex = session.messages.length - 2;
+                                isFirstToolInTurn = true;
                             }
                             // Get the latest context
                             const latestContext = session.context.length > 0
                                 ? session.context[session.context.length - 1]
                                 : undefined;
                             // Build message entries for the new context
-                            // Check if we already have a pointer to this message (during mid-turn updates)
                             const existingMessages = latestContext?.messages ?? [];
-                            const lastEntry = existingMessages[existingMessages.length - 1];
-                            const alreadyHasPointer = lastEntry?.type === "pointer" &&
-                                lastEntry.index === partialMessageIndex;
-                            const messageEntries = alreadyHasPointer
-                                ? existingMessages // Don't add duplicate pointer
-                                : [
+                            // Check if we already have pointers to these messages
+                            const hasUserPointer = existingMessages.some((entry) => entry.type === "pointer" && entry.index === userMessageIndex);
+                            const hasAssistantPointer = existingMessages.some((entry) => entry.type === "pointer" &&
+                                entry.index === partialMessageIndex);
+                            let messageEntries;
+                            if (isFirstToolInTurn && !hasUserPointer) {
+                                // First tool: add both user and assistant pointers
+                                messageEntries = [
                                     ...existingMessages,
+                                    { type: "pointer", index: userMessageIndex },
                                     { type: "pointer", index: partialMessageIndex },
                                 ];
+                            }
+                            else if (!hasAssistantPointer) {
+                                // Subsequent tool or user already added: just update/add assistant pointer
+                                messageEntries = [
+                                    ...existingMessages,
+                                    { type: "pointer", index: partialMessageIndex },
+                                ];
+                            }
+                            else {
+                                // Both pointers already exist (updating existing assistant message)
+                                messageEntries = existingMessages;
+                            }
                             // Resolve message entries to actual messages
                             const contextMessages = [];
                             for (const entry of messageEntries) {
@@ -977,13 +1049,19 @@ export class AgentAcpAdapter {
                 ? session.context[session.context.length - 1]
                 : undefined;
             // Calculate final context size
-            // Build message pointers for the new context
+            // Build message pointers for the new context (add both user and assistant messages)
+            const userMessageIndex = session.messages.length - 2;
+            const assistantMessageIndex = session.messages.length - 1;
             const messageEntries = previousContext
                 ? [
                     ...previousContext.messages,
-                    { type: "pointer", index: session.messages.length - 1 },
+                    { type: "pointer", index: userMessageIndex },
+                    { type: "pointer", index: assistantMessageIndex },
                 ]
-                : [{ type: "pointer", index: session.messages.length - 1 }];
+                : [
+                    { type: "pointer", index: userMessageIndex },
+                    { type: "pointer", index: assistantMessageIndex },
+                ];
             // Resolve message entries to actual messages
             const contextMessages = [];
             for (const entry of messageEntries) {

package/dist/acp-server/http.js

@@ -10,6 +10,7 @@ import { streamSSE } from "hono/streaming";
 import { createLogger, isSubagent } from "../logger.js";
 import { makeRunnerFromDefinition } from "../runner";
 import { AgentAcpAdapter } from "./adapter";
+import { SessionStorage } from "./session-storage";
 const logger = createLogger("http");
 /**
  * Compress a payload using gzip if it's too large for PostgreSQL NOTIFY
@@ -65,10 +66,19 @@ export function makeHttpTransport(agent, agentDir, agentName) {
     const outbound = new TransformStream();
     const bridge = acp.ndJsonStream(outbound.writable, inbound.readable);
     const agentRunner = "definition" in agent ? agent : makeRunnerFromDefinition(agent);
-    new acp.AgentSideConnection((conn) => new AgentAcpAdapter(agentRunner, conn, agentDir, agentName), bridge);
+    // Store adapter reference so we can call methods on it (e.g., storeInitialMessage)
+    let acpAdapter = null;
+    new acp.AgentSideConnection((conn) => {
+        acpAdapter = new AgentAcpAdapter(agentRunner, conn, agentDir, agentName);
+        return acpAdapter;
+    }, bridge);
     const app = new Hono();
     // Track active SSE streams by sessionId for direct output delivery
     const sseStreams = new Map();
+    // Track sessions that have already received initial message
+    const initialMessageSentSessions = new Set();
+    // Get initial message config from agent definition
+    const initialMessageConfig = agentRunner.definition.initialMessage;
     const decoder = new TextDecoder();
     const encoder = new TextEncoder();
     (async () => {
@@ -270,6 +280,28 @@ export function makeHttpTransport(agent, agentDir, agentName) {
         allowMethods: ["GET", "POST", "OPTIONS"],
     }));
     app.get("/health", (c) => c.json({ ok: true }));
+    // List available sessions
+    app.get("/sessions", async (c) => {
+        if (!agentDir || !agentName) {
+            return c.json({ sessions: [], error: "Session storage not configured" });
+        }
+        const noSession = process.env.TOWN_NO_SESSION === "true";
+        if (noSession) {
+            return c.json({ sessions: [], error: "Sessions disabled" });
+        }
+        try {
+            const storage = new SessionStorage(agentDir, agentName);
+            const sessions = await storage.listSessionsWithMetadata();
+            return c.json({ sessions });
+        }
+        catch (error) {
+            logger.error("Failed to list sessions", { error });
+            return c.json({
+                sessions: [],
+                error: error instanceof Error ? error.message : String(error),
+            }, 500);
+        }
+    });
     // Serve static files from agent directory (for generated images, etc.)
     if (agentDir) {
         app.get("/static/*", async (c) => {
@@ -319,6 +351,47 @@ export function makeHttpTransport(agent, agentDir, agentName) {
             // Register this stream for direct tool output delivery
             sseStreams.set(sessionId, stream);
             await stream.writeSSE({ event: "ping", data: "{}" });
+            // Send initial message if configured and not already sent for this session
+            if (initialMessageConfig?.enabled &&
+                initialMessageConfig.content &&
+                !initialMessageSentSessions.has(sessionId)) {
+                initialMessageSentSessions.add(sessionId);
+                // Process template variables in the content
+                let content = initialMessageConfig.content;
+                content = content.replace(/\{\{\.AgentName\}\}/g, agentName ?? "Agent");
+                const displayName = agentRunner.definition.displayName;
+                content = content.replace(/\{\{\.DisplayName\}\}/g, displayName ?? agentName ?? "Agent");
+                const initialMessage = {
+                    jsonrpc: "2.0",
+                    method: "session/update",
+                    params: {
+                        sessionId,
+                        update: {
+                            sessionUpdate: "agent_message_chunk",
+                            content: {
+                                type: "text",
+                                text: content,
+                            },
+                            _meta: {
+                                isInitialMessage: true,
+                                isReplay: true, // Mark as replay so UI adds it to messages
+                            },
+                        },
+                    },
+                };
+                await stream.writeSSE({
+                    event: "message",
+                    data: JSON.stringify(initialMessage),
+                });
+                // Store the initial message in the session for persistence
+                if (acpAdapter) {
+                    await acpAdapter.storeInitialMessage(sessionId, content);
+                }
+                logger.info("Sent initial message via SSE", {
+                    sessionId,
+                    contentPreview: content.slice(0, 100),
+                });
+            }
             const hb = setInterval(() => {
                 // Heartbeat to keep proxies from terminating idle connections
                 void stream.writeSSE({ event: "ping", data: "{}" });

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

@@ -150,4 +150,18 @@ export declare class SessionStorage {
      * List all session IDs
      */
     listSessions(): Promise<string[]>;
+    /**
+     * Session summary for listing
+     */
+    /**
+     * List all sessions with metadata
+     * Returns sessions sorted by updatedAt (most recent first)
+     */
+    listSessionsWithMetadata(): Promise<Array<{
+        sessionId: string;
+        createdAt: string;
+        updatedAt: string;
+        messageCount: number;
+        firstUserMessage?: string;
+    }>>;
 }

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

@@ -236,4 +236,51 @@ export class SessionStorage {
             throw new Error(`Failed to list sessions: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Session summary for listing
+     */
+    /**
+     * List all sessions with metadata
+     * Returns sessions sorted by updatedAt (most recent first)
+     */
+    async listSessionsWithMetadata() {
+        if (!existsSync(this.sessionsDir)) {
+            return [];
+        }
+        try {
+            const files = readdirSync(this.sessionsDir);
+            const sessionFiles = files.filter((file) => file.endsWith(".json") && !file.endsWith(".tmp"));
+            const sessions = [];
+            for (const file of sessionFiles) {
+                const sessionId = file.replace(".json", "");
+                try {
+                    const session = this.loadSessionSync(sessionId);
+                    if (session) {
+                        // Find the first user message for preview
+                        const firstUserMsg = session.messages.find((m) => m.role === "user");
+                        const firstUserText = firstUserMsg?.content.find((c) => c.type === "text");
+                        const entry = {
+                            sessionId: session.sessionId,
+                            createdAt: session.metadata.createdAt,
+                            updatedAt: session.metadata.updatedAt,
+                            messageCount: session.messages.length,
+                        };
+                        if (firstUserText && "text" in firstUserText) {
+                            entry.firstUserMessage = firstUserText.text.slice(0, 100);
+                        }
+                        sessions.push(entry);
+                    }
+                }
+                catch {
+                    // Skip invalid sessions
+                }
+            }
+            // Sort by updatedAt, most recent first
+            sessions.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+            return sessions;
+        }
+        catch (error) {
+            throw new Error(`Failed to list sessions: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
 }

package/dist/definition/index.d.ts

@@ -26,6 +26,15 @@ export declare const HookConfigSchema: z.ZodObject<{
     }, z.core.$strip>]>>;
     callback: z.ZodString;
 }, z.core.$strip>;
+/** Initial message configuration schema. */
+export declare const InitialMessageSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    content: z.ZodString;
+}, z.core.$strip>;
+/** UI configuration schema for controlling the chat interface appearance. */
+export declare const UiConfigSchema: z.ZodObject<{
+    hideTopBar: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 /** Agent definition schema. */
 export declare const AgentDefinitionSchema: z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
@@ -74,4 +83,11 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
         }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;
+    initialMessage: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+    uiConfig: z.ZodOptional<z.ZodObject<{
+        hideTopBar: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/definition/index.js

@@ -71,6 +71,18 @@ export const HookConfigSchema = z.object({
         .optional(),
     callback: z.string(),
 });
+/** Initial message configuration schema. */
+export const InitialMessageSchema = z.object({
+    /** Whether the agent should send an initial message when a session starts. */
+    enabled: z.boolean(),
+    /** The content of the initial message to send. Supports template variables like {{.AgentName}}. */
+    content: z.string(),
+});
+/** UI configuration schema for controlling the chat interface appearance. */
+export const UiConfigSchema = z.object({
+    /** Whether to hide the top bar (session switcher, debugger link, settings). Useful for embedded/deployed mode. */
+    hideTopBar: z.boolean().optional(),
+});
 /** Agent definition schema. */
 export const AgentDefinitionSchema = z.object({
     /** Human-readable display name for the agent (shown in UI). */
@@ -84,4 +96,8 @@ export const AgentDefinitionSchema = z.object({
     mcps: z.array(McpConfigSchema).optional(),
     harnessImplementation: z.literal("langchain").optional(),
     hooks: z.array(HookConfigSchema).optional(),
+    /** Configuration for an initial message the agent sends when a session starts. */
+    initialMessage: InitialMessageSchema.optional(),
+    /** UI configuration for controlling the chat interface appearance. */
+    uiConfig: UiConfigSchema.optional(),
 });

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

@@ -8,7 +8,7 @@ export declare const zAgentRunnerParams: z.ZodObject<{
     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.ZodLiteral<"generate_image">]>, z.ZodObject<{
+    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.ZodLiteral<"generate_image">, z.ZodLiteral<"browser">]>, z.ZodObject<{
         type: z.ZodLiteral<"custom">;
         modulePath: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -52,6 +52,13 @@ export declare const zAgentRunnerParams: z.ZodObject<{
         }, z.core.$strip>]>>;
         callback: z.ZodString;
     }, z.core.$strip>>>;
+    initialMessage: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+    uiConfig: z.ZodOptional<z.ZodObject<{
+        hideTopBar: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CreateAgentRunnerParams = z.infer<typeof zAgentRunnerParams>;
 export interface SessionMessage {

package/dist/runner/agent-runner.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { HookConfigSchema, McpConfigSchema } from "../definition";
+import { HookConfigSchema, InitialMessageSchema, McpConfigSchema, UiConfigSchema, } from "../definition";
 import { zToolType } from "./tools";
 export const zAgentRunnerParams = z.object({
     displayName: z.string().optional(),
@@ -11,4 +11,6 @@ export const zAgentRunnerParams = z.object({
     tools: z.array(zToolType).optional(),
     mcps: z.array(McpConfigSchema).optional(),
     hooks: z.array(HookConfigSchema).optional(),
+    initialMessage: InitialMessageSchema.optional(),
+    uiConfig: UiConfigSchema.optional(),
 });