@tenex-chat/backend 0.9.1

package/src/tools/implementations/agents_read.ts

@@ -0,0 +1,173 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import type { EffectiveInstructionsCacheEntry } from "@/services/prompt-compiler";
+import { PromptCompilerService } from "@/services/prompt-compiler";
+import { getProjectContext } from "@/services/projects";
+import { ReportService } from "@/services/reports";
+import { logger } from "@/utils/logger";
+import * as fs from "node:fs/promises";
+import { tool } from "ai";
+import { z } from "zod";
+
+// Define the input schema
+const agentsReadSchema = z.object({
+    slug: z.string().describe("The slug identifier of the agent to read"),
+});
+
+type AgentsReadInput = z.infer<typeof agentsReadSchema>;
+
+// Define the report shape returned in the response
+interface MemorizedReport {
+    slug: string;
+    title?: string;
+    content?: string;
+    publishedAt?: number;
+}
+
+// Define the output type — all fields are always present for a consistent response contract
+interface AgentsReadOutput {
+    success: boolean;
+    message?: string;
+    error?: string;
+    agent?: {
+        slug: string;
+        name: string;
+        role: string;
+        description?: string;
+        instructions?: string;
+        compiledInstructions: string | null;
+        memorizedReports: MemorizedReport[];
+        useCriteria?: string;
+        llmConfig?: string;
+        tools?: string[];
+        eventId?: string;
+        pubkey: string;
+    };
+}
+
+/**
+ * Read compiled (effective) instructions from the PromptCompilerService disk cache.
+ * Uses the shared static helper from PromptCompilerService for the cache path.
+ *
+ * @returns The compiled instructions string, or null if no cache exists
+ */
+async function readCompiledInstructions(agentPubkey: string): Promise<string | null> {
+    try {
+        const cachePath = PromptCompilerService.getCachePathForAgent(agentPubkey);
+        const data = await fs.readFile(cachePath, "utf-8");
+        const entry = JSON.parse(data) as EffectiveInstructionsCacheEntry;
+        return entry.effectiveAgentInstructions;
+    } catch {
+        // No cache file or invalid JSON — compiled instructions not available
+        return null;
+    }
+}
+
+/**
+ * Read memorized reports for an agent from the ReportService cache.
+ * Returns team reports first, then agent-specific reports (deduped by slug).
+ * Each report includes publishedAt for chronological ordering by consumers.
+ *
+ * @returns Array of memorized report summaries, or empty array
+ */
+function readMemorizedReports(agentPubkey: string): MemorizedReport[] {
+    try {
+        const reportService = new ReportService();
+        const agentReports = reportService.getMemorizedReportsForAgent(agentPubkey);
+        const teamReports = reportService.getTeamMemorizedReports();
+
+        // Deduplicate: team reports take precedence over agent reports with the same slug
+        const teamSlugs = new Set(teamReports.map(r => r.slug));
+        const combined = [
+            ...teamReports,
+            ...agentReports.filter(r => !teamSlugs.has(r.slug)),
+        ];
+
+        return combined
+            .filter(r => !r.isDeleted)
+            .map(r => ({
+                slug: r.slug,
+                title: r.title,
+                content: r.content,
+                publishedAt: r.publishedAt,
+            }));
+    } catch {
+        // ReportService may fail if no project context — return empty
+        return [];
+    }
+}
+
+/**
+ * Core implementation of reading agents.
+ * Returns both the base agent definition and compiled runtime data when available.
+ */
+async function executeAgentsRead(
+    input: AgentsReadInput,
+    _context: ToolExecutionContext
+): Promise<AgentsReadOutput> {
+    const { slug } = input;
+
+    if (!slug) {
+        throw new Error("Agent slug is required");
+    }
+
+    // Get agent from project context
+    const projectCtx = getProjectContext();
+    const agent = projectCtx.getAgent(slug);
+
+    if (!agent) {
+        throw new Error(`Agent with slug "${slug}" not found in current project`);
+    }
+
+    // Fetch compiled instructions from disk cache (non-blocking, best-effort)
+    const compiledInstructions = await readCompiledInstructions(agent.pubkey);
+
+    // Fetch memorized reports from in-memory cache (synchronous, best-effort)
+    const memorizedReports = readMemorizedReports(agent.pubkey);
+
+    logger.info(`Successfully read agent definition for "${agent.name}" (${slug})`, {
+        hasCompiledInstructions: compiledInstructions !== null,
+        memorizedReportsCount: memorizedReports.length,
+    });
+
+    return {
+        success: true,
+        message: `Successfully read agent definition for "${agent.name}"`,
+        agent: {
+            slug: agent.slug,
+            name: agent.name,
+            role: agent.role,
+            description: agent.description,
+            instructions: agent.instructions,
+            compiledInstructions,
+            memorizedReports,
+            useCriteria: agent.useCriteria,
+            llmConfig: agent.llmConfig,
+            tools: agent.tools,
+            eventId: agent.eventId,
+            pubkey: agent.pubkey,
+        },
+    };
+}
+
+/**
+ * Create an AI SDK tool for reading agents
+ * This is the primary implementation
+ */
+export function createAgentsReadTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Read a local agent definition, including base instructions and compiled runtime instructions when available",
+        inputSchema: agentsReadSchema,
+        execute: async (input: AgentsReadInput) => {
+            try {
+                return await executeAgentsRead(input, context);
+            } catch (error) {
+                logger.error("Failed to read agent definition", { error });
+                throw new Error(
+                    `Failed to read agent definition: ${error instanceof Error ? error.message : String(error)}`,
+                    { cause: error }
+                );
+            }
+        },
+    }) as AISdkTool;
+}

package/src/tools/implementations/agents_write.ts

@@ -0,0 +1,200 @@
+import { agentStorage, createStoredAgent } from "@/agents/AgentStorage";
+import { createAgentInstance } from "@/agents/agent-loader";
+import { CORE_AGENT_TOOLS, DELEGATE_TOOLS } from "@/agents/constants";
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { DEFAULT_AGENT_LLM_CONFIG } from "@/llm/constants";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import { NDKPrivateKeySigner } from "@nostr-dev-kit/ndk";
+import { tool } from "ai";
+import { z } from "zod";
+// Define the input schema
+const agentsWriteSchema = z.object({
+    slug: z.string().describe("The slug identifier for the agent"),
+    name: z.string().describe("Display name of the agent"),
+    role: z.string().describe("Primary role/function of the agent"),
+    instructions: z.string().describe("System instructions that guide agent behavior"),
+    useCriteria: z.string().describe("Criteria for when this agent should be selected"),
+    llmConfig: z.string().nullable().describe("LLM configuration identifier"),
+    tools: z
+        .array(z.string())
+        .nullable()
+        .describe("List of tool names to make available to this agent"),
+});
+
+type AgentsWriteInput = z.infer<typeof agentsWriteSchema>;
+
+// Define the output type
+interface AgentsWriteOutput {
+    success: boolean;
+    message?: string;
+    error?: string;
+    filePath?: string;
+    agent?: {
+        slug: string;
+        name: string;
+        pubkey: string;
+    };
+}
+
+/**
+ * Core implementation of the agents_write functionality
+ * Shared between AI SDK and legacy Tool interfaces
+ */
+async function executeAgentsWrite(
+    input: AgentsWriteInput,
+    context?: ToolExecutionContext
+): Promise<AgentsWriteOutput> {
+    const { slug, name, role, instructions, useCriteria, llmConfig, tools: rawTools } =
+        input;
+
+    // Normalize and filter tools
+    const autoInjectedTools = new Set<string>([...CORE_AGENT_TOOLS, ...DELEGATE_TOOLS]);
+    const tools = rawTools === null ? null : rawTools
+        // 1. Strip mcp__tenex__ prefix
+        .map(t => t.startsWith("mcp__tenex__") ? t.slice("mcp__tenex__".length) : t)
+        // 2. Filter out auto-injected tools
+        .filter(t => !autoInjectedTools.has(t));
+
+    if (!slug) {
+        return {
+            success: false,
+            error: "Agent slug is required",
+        };
+    }
+
+    if (!name || !role) {
+        return {
+            success: false,
+            error: `Agent ${name ? "role" : "name"} is required`,
+        };
+    }
+
+    // Get project context
+    const projectContext = getProjectContext();
+
+    if (!context?.workingDirectory) {
+        throw new Error("ToolExecutionContext with workingDirectory is required for agents_write tool");
+    }
+
+    // Check if agent exists by slug
+    const existingAgent = await agentStorage.getAgentBySlug(slug);
+
+    if (existingAgent) {
+        logger.info(`Updating existing agent: ${slug}`);
+
+        // Update fields
+        existingAgent.name = name;
+        existingAgent.role = role;
+        existingAgent.instructions = instructions;
+        existingAgent.useCriteria = useCriteria;
+        if (llmConfig !== undefined || tools !== undefined) {
+            if (!existingAgent.default) existingAgent.default = {};
+            if (llmConfig !== undefined) existingAgent.default.model = llmConfig ?? undefined;
+            if (tools !== undefined) existingAgent.default.tools = tools ?? undefined;
+        }
+
+        // Save to storage
+        await agentStorage.saveAgent(existingAgent);
+
+        // Reload project context to pick up changes
+        await projectContext.updateProjectData(projectContext.project);
+
+        const agent = projectContext.getAgent(slug);
+        if (!agent) {
+            return {
+                success: false,
+                error: `Agent ${slug} updated in storage but not found in project context`,
+            };
+        }
+
+        logger.info(`Successfully updated agent "${name}" (${slug})`);
+        logger.info(`  Pubkey: ${agent.pubkey}`);
+
+        return {
+            success: true,
+            message: `Successfully updated agent "${name}"`,
+            agent: {
+                slug,
+                name,
+                pubkey: agent.pubkey,
+            },
+        };
+    }
+    logger.info(`Creating new agent: ${slug}`);
+
+    // Generate a new private key for this agent
+    const signer = NDKPrivateKeySigner.generate();
+
+    // Get project d-tag for consistent storage keys
+    // AgentRegistry uses dTag to lookup agents, so we must use the same key format
+    const projectDTag = projectContext.project.dTag || projectContext.project.tagValue("d");
+    if (!projectDTag) {
+        throw new Error(
+            "Project is missing d-tag. Cannot associate agent with project without a valid d-tag identifier."
+        );
+    }
+
+    // Create StoredAgent using factory
+    const storedAgent = createStoredAgent({
+        nsec: signer.nsec,
+        slug,
+        name,
+        role,
+        instructions,
+        useCriteria,
+        defaultConfig: {
+            model: llmConfig || DEFAULT_AGENT_LLM_CONFIG,
+            tools: tools ?? undefined,
+        },
+        eventId: undefined, // Locally created agents don't have event IDs
+    });
+
+    // Save to storage, then associate with project
+    await agentStorage.saveAgent(storedAgent);
+    await agentStorage.addAgentToProject(signer.pubkey, projectDTag);
+
+    // Create instance and add to registry
+    // Pass projectDTag for project-scoped config resolution
+    const agent = createAgentInstance(storedAgent, projectContext.agentRegistry, projectDTag);
+    projectContext.agentRegistry.addAgent(agent);
+
+    // Notify context that a new agent was added (for Daemon routing synchronization)
+    projectContext.notifyAgentAdded(agent);
+
+    logger.info(`Successfully created agent "${name}" (${slug})`);
+    logger.info(`  Pubkey: ${agent.pubkey}`);
+
+    return {
+        success: true,
+        message: `Successfully created agent "${name}"`,
+        agent: {
+            slug,
+            name,
+            pubkey: agent.pubkey,
+        },
+    };
+}
+
+/**
+ * Create an AI SDK tool for writing agents
+ * This is the primary implementation
+ */
+export function createAgentsWriteTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Write or update agent configuration and tools. Creates/updates agent definition files in .tenex/agents/. Core tools are automatically injected (lessons, reports, todos, conversation tools, kill). Delegation tools (ask, delegate, delegate_crossproject, delegate_followup) are automatically assigned - do not include them. Assign additional tools based on responsibilities. Agent activates immediately and becomes available for delegation. Use to create specialized agents for specific tasks or update existing agent configurations. Changes persist across sessions.",
+        inputSchema: agentsWriteSchema,
+        execute: async (input: AgentsWriteInput) => {
+            try {
+                return await executeAgentsWrite(input, context);
+            } catch (error) {
+                logger.error("Failed to write agent definition", { error });
+                throw new Error(
+                    `Failed to write agent definition: ${error instanceof Error ? error.message : String(error)}`,
+                    { cause: error }
+                );
+            }
+        },
+    }) as AISdkTool;
+}