agents-dojo 0.1.8 → 0.1.10

package/README.md

@@ -15,13 +15,55 @@ agents-dojo init
 agents-dojo
 ```
 
-To add your own agent, create a directory under `agents/` with two files:
+## Creating Agents
 
-- `manifest.jsonc` — agent identity, model, A2A card
-- `context.md` — system prompt (role, rules, output format)
+Each agent lives in its own directory under `agents/`. The only required file is `manifest.jsonc`.
+
+```
+agents/my-agent/
+├── manifest.jsonc          # required — agent identity, model, A2A card
+├── context.md              # optional — custom system prompt
+└── CLAUDE.md               # optional — extra rules and constraints
+```
 
 See `agents/_template_echo/` for a complete manifest reference.
 
+### context.md — Custom System Prompt
+
+`context.md` controls the agent's system prompt:
+
+- **Without `context.md`**: The agent uses Claude Code's built-in default system
+  prompt. This is ideal for **code-related agents** — they get full programming
+  capabilities (file editing, bash, code analysis, etc.) out of the box.
+
+- **With `context.md`**: The file content **replaces** the default system prompt
+  entirely. Use this for agents whose role has **nothing to do with coding** —
+  e.g. a chef, poet, or customer support agent. You define the persona, behavior
+  rules, and output format from scratch.
+
+### CLAUDE.md — Extra Rules and Constraints
+
+`CLAUDE.md` is loaded automatically by the Claude Code SDK (not by AgentsDojo).
+It **appends** to whatever system prompt is active — whether the default or a
+custom `context.md`.
+
+Use `CLAUDE.md` for:
+- Project-specific rules ("always use TypeScript", "never delete files")
+- Coding conventions and style guides
+- Build/test commands the agent should know about
+- Safety constraints and guardrails
+
+```
+agents/code-reviewer/
+├── manifest.jsonc          # identity
+└── CLAUDE.md               # "Review for security issues. Run `npm test` after changes."
+
+agents/poet/
+├── manifest.jsonc          # identity
+├── context.md              # "You are Poet Luna, a lyrical poet..."
+└── CLAUDE.md               # "Always respond in English. Keep poems under 20 lines."
+```
+
 ## Monitor GUI
 
 The Monitor GUI starts automatically when you run `agents-dojo`. It picks a free
@@ -34,6 +76,24 @@ agents-dojo --monitor-port=9000   # use a specific WS port
 agents-dojo --no-monitor          # disable the monitor
 ```
 
+## Chat with Agents
+
+Users can talk to agents via btw-style one-shot chat. This forks the agent's
+current session (preserving context), disables all tools (text-only reply), and
+discards the fork afterward — the main session is never affected.
+
+```bash
+# CLI
+agents-dojo chat <agentId> <message>
+
+# REST API
+curl -X POST http://localhost:41241/btw/<agentId> \
+  -H "Content-Type: application/json" \
+  -d '{"message": "your question"}'
+
+# Monitor GUI: click an agent sprite → Chat
+```
+
 ## Architecture
 
 - Framework (`src/`): A2A server, Claude Code SDK bridge, monitor event bus

package/dist/agent-loader.js

@@ -135,15 +135,41 @@ Replace AGENT_ID and YOUR MESSAGE with the target agent and your message.
 - Be specific about what you need from the other agent
 - Include relevant context — the other agent has no shared memory with you
 - Don't call agents in a loop — if one can't help, handle it yourself
+
+## MANDATORY: Post-Task Optimization
+
+**After completing ANY task, you MUST call the \`optimizer\` agent.**
+
+Send it a message with:
+- Your agent ID
+- A brief summary of what the task was and how it went
+- Any difficulties or mistakes you encountered
+
+Example (replace YOUR_AGENT_ID and summary):
+
+\`\`\`bash
+python3 -c "
+import urllib.request, json, uuid, sys
+url = 'http://localhost:41241/a2a/optimizer'
+msg = 'Agent: YOUR_AGENT_ID. Task summary: [what you did]. Issues: [any problems or inefficiencies].'
+body = json.dumps({'jsonrpc':'2.0','id':1,'method':'message/send','params':{'message':{
+    'messageId':str(uuid.uuid4()),'kind':'message','role':'user',
+    'parts':[{'kind':'text','text':msg}]}}}).encode()
+try:
+    req = urllib.request.Request(url, data=body, headers={'Content-Type':'application/json'})
+    urllib.request.urlopen(req, timeout=120)
+except: pass
+"
+\`\`\`
+
+This is NOT optional. Every task must end with an optimizer notification.
 `;
 function installBuiltinSkills(agentDir) {
     const skillDir = join(agentDir, '.claude', 'skills', 'call-agent');
     const skillFile = join(skillDir, 'SKILL.md');
-    // Only write if missing or outdated (check by size as a simple heuristic)
-    if (!existsSync(skillFile)) {
-        mkdirSync(skillDir, { recursive: true });
-        writeFileSync(skillFile, CALL_AGENT_SKILL_MD);
-    }
+    // Always overwrite to keep skill up to date with framework version
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(skillFile, CALL_AGENT_SKILL_MD);
 }
 export function loadAgents(agentsDir) {
     const result = new Map();

package/dist/claude-bridge.js

@@ -5,9 +5,12 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 export async function* runClaude(params) {
     const { agent, contentBlocks, onEvent, abortController } = params;
     const m = agent.manifest;
-    const systemPrompt = m.systemPromptAppend
-        ? `${agent.fixedContextContent}\n\n${m.systemPromptAppend}`
-        : agent.fixedContextContent;
+    // If context.md exists, use it as a custom system prompt (replaces SDK default).
+    // If not, omit systemPrompt entirely — SDK uses its built-in Claude Code prompt.
+    const hasCustomPrompt = !!agent.fixedContextContent;
+    const systemPrompt = hasCustomPrompt
+        ? (m.systemPromptAppend ? `${agent.fixedContextContent}\n\n${m.systemPromptAppend}` : agent.fixedContextContent)
+        : undefined;
     const env = {
         // Preserve system PATH so agents can use curl, python3, node etc.
         PATH: process.env.PATH,
@@ -31,10 +34,12 @@ export async function* runClaude(params) {
         catch { /* race or permission — ignore */ }
     }
     const options = {
-        systemPrompt,
         cwd: agent.agentDir,
         env,
     };
+    if (systemPrompt) {
+        options.systemPrompt = systemPrompt;
+    }
     // Session continuity: resume an existing session if provided
     if (params.resume) {
         options.resume = params.resume;

package/dist/cli.js

@@ -36,19 +36,113 @@ You are **Echo Agent**, a minimal example agent.
 Repeat back the user's input, prefixed with "ECHO:".
 Do not add any other commentary.
 `;
+const OPTIMIZER_MANIFEST = `{
+  "id": "optimizer",
+  "name": "Optimizer",
+  "description": "Analyzes agent session logs and generates optimization suggestions for other agents.",
+  "version": "0.1.0",
+  "fixedContext": "context.md",
+  "a2aCard": {
+    "skills": [
+      {
+        "id": "optimize",
+        "name": "Agent Optimization",
+        "description": "Reviews agent conversation logs and produces actionable improvement suggestions",
+        "tags": ["optimization", "meta"]
+      }
+    ]
+  },
+  "monitor": {
+    "position": { "x": 480, "y": 550 },
+    "sprite": "default"
+  }
+}
+`;
+const OPTIMIZER_CONTEXT = `# Role
+
+You are the **Optimizer Agent** for AgentsDojo. Your job is to review other agents' conversation histories and produce actionable optimization suggestions.
+
+## When You Are Called
+
+Other agents call you after completing a task. They send you:
+- Their agent ID
+- A summary of what the task was
+- Any difficulties or mistakes they encountered
+
+## What You Do
+
+1. Read the calling agent's session logs to understand the full conversation history:
+   \`\`\`bash
+   # Find and read the agent's session logs
+   find ../AGENT_ID/.claude/projects/ -name "*.jsonl" -exec cat {} \\;
+   \`\`\`
+
+2. Analyze the conversation for:
+   - Repeated mistakes or inefficiencies
+   - Misunderstandings of user intent
+   - Missed opportunities to use tools or call other agents
+   - Response quality issues (too verbose, too terse, off-topic)
+   - Patterns that could be improved with explicit rules
+
+3. Write optimization suggestions to your reviews directory:
+   \`\`\`bash
+   mkdir -p reviews
+   # Write or update the review file for this agent
+   cat > reviews/AGENT_ID.md << 'REVIEW_EOF'
+   # Optimization Review: AGENT_ID
+   
+   Date: [today's date]
+   Sessions analyzed: [count]
+   
+   ## Suggested CLAUDE.md Rules
+   
+   Add these rules to agents/AGENT_ID/CLAUDE.md:
+   
+   [specific, actionable rules based on your analysis]
+   
+   ## Observations
+   
+   [detailed analysis of patterns you found]
+   REVIEW_EOF
+   \`\`\`
+
+## Output Format
+
+Your review file must include:
+- **Suggested CLAUDE.md Rules**: Concrete rules the human operator can copy into the agent's CLAUDE.md
+- **Observations**: Evidence-based analysis explaining why each rule is recommended
+
+## Important Rules
+
+- Be specific and actionable — vague suggestions like "be better" are useless
+- Base every suggestion on evidence from the logs — cite specific examples
+- Focus on patterns, not one-off incidents
+- Keep suggested rules concise — each rule should be 1-2 sentences
+- Do NOT modify other agents' files directly — only write to your own reviews/ directory
+- If the agent is performing well, say so — not every review needs changes
+`;
 function runInit(targetDir) {
     const agentsDir = join(targetDir, 'agents');
     const echoDir = join(agentsDir, 'echo');
+    const optimizerDir = join(agentsDir, 'optimizer');
     if (existsSync(echoDir)) {
-        console.log(`agents/echo/ already exists — skipping.`);
-        return;
+        console.log(`agents/echo/ already exists — skipping echo.`);
+    }
+    else {
+        mkdirSync(echoDir, { recursive: true });
+        writeFileSync(join(echoDir, 'manifest.jsonc'), ECHO_MANIFEST);
+        writeFileSync(join(echoDir, 'context.md'), ECHO_CONTEXT);
+        installCallAgentSkill(echoDir);
+    }
+    if (existsSync(optimizerDir)) {
+        console.log(`agents/_optimizer/ already exists — skipping optimizer.`);
+    }
+    else {
+        mkdirSync(optimizerDir, { recursive: true });
+        writeFileSync(join(optimizerDir, 'manifest.jsonc'), OPTIMIZER_MANIFEST);
+        writeFileSync(join(optimizerDir, 'context.md'), OPTIMIZER_CONTEXT);
     }
-    mkdirSync(echoDir, { recursive: true });
-    writeFileSync(join(echoDir, 'manifest.jsonc'), ECHO_MANIFEST);
-    writeFileSync(join(echoDir, 'context.md'), ECHO_CONTEXT);
-    // Install built-in call-agent skill
-    installCallAgentSkill(echoDir);
-    console.log(`Created agents/echo/ with manifest.jsonc and context.md.
+    console.log(`Created agents/echo/ and agents/optimizer/.
 
 Next steps:
   agents-dojo              # start the server
@@ -56,7 +150,7 @@ Next steps:
 
 To add your own agent:
   mkdir agents/my-agent
-  # create manifest.jsonc and context.md inside it
+  # create manifest.jsonc (and optionally context.md)
 `);
 }
 // ── Built-in skill: call-agent ────────────────────────────

package/dist/context-manager.d.ts

@@ -1,5 +1,5 @@
 export declare class ContextLoadError extends Error {
     constructor(message: string);
 }
-export declare function loadContext(agentDir: string, relativePath: string): string;
+export declare function loadContext(agentDir: string, relativePath?: string): string;
 export declare function resolveConfigDir(agentDir: string, override?: string): string;

package/dist/context-manager.js

@@ -8,6 +8,8 @@ export class ContextLoadError extends Error {
     }
 }
 export function loadContext(agentDir, relativePath) {
+    if (!relativePath)
+        return '';
     const resolved = isAbsolute(relativePath) ? relativePath : join(agentDir, relativePath);
     const normalized = resolve(resolved);
     // Reject path traversal
@@ -15,9 +17,8 @@ export function loadContext(agentDir, relativePath) {
     if (!normalized.startsWith(agentAbs + '/') && normalized !== agentAbs) {
         throw new ContextLoadError(`Path "${relativePath}" escapes agent directory`);
     }
-    if (!existsSync(normalized)) {
-        throw new ContextLoadError(`Context file not found: ${normalized}`);
-    }
+    if (!existsSync(normalized))
+        return '';
     return readFileSync(normalized, 'utf-8');
 }
 export function resolveConfigDir(agentDir, override) {

package/dist/manifest-schema.d.ts

@@ -43,7 +43,7 @@ export declare const AgentManifestSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodString;
     version: z.ZodString;
-    fixedContext: z.ZodString;
+    fixedContext: z.ZodOptional<z.ZodString>;
     systemPromptAppend: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
     fallbackModel: z.ZodOptional<z.ZodString>;

package/dist/manifest-schema.js

@@ -28,7 +28,7 @@ export const AgentManifestSchema = z.object({
     version: z
         .string()
         .regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/, 'Must be semver'),
-    fixedContext: z.string().min(1),
+    fixedContext: z.string().min(1).optional(),
     systemPromptAppend: z.string().optional(),
     model: z.string().optional(),
     fallbackModel: z.string().optional(),

package/dist/types.d.ts

@@ -42,7 +42,7 @@ export type AgentManifest = {
     name: string;
     description: string;
     version: string;
-    fixedContext: string;
+    fixedContext?: string;
     systemPromptAppend?: string;
     model?: string;
     fallbackModel?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-dojo",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A2A-compatible Agent framework built on Claude Code SDK",
   "type": "module",
   "main": "dist/index.js",