agents-dojo 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# AgentsDojo
+
+A Claude Code SDK-based Agent framework with A2A protocol support and a pixel-art Monitor GUI.
+
+## Quick Start
+
+```bash
+npm install -g agents-dojo
+
+# Create a project with a sample agent
+mkdir my-project && cd my-project
+agents-dojo init
+
+# Start the server
+agents-dojo
+```
+
+To add your own agent, create a directory under `agents/` with two files:
+
+- `manifest.jsonc` — agent identity, model, A2A card
+- `context.md` — system prompt (role, rules, output format)
+
+See `agents/_template_echo/` for a complete manifest reference.
+
+## Monitor GUI
+
+```bash
+agents-dojo --monitor-port=41242
+cd monitor && npm install && npm run dev
+# Open http://localhost:5173
+```
+
+## Architecture
+
+- Framework (`src/`): A2A server, Claude Code SDK bridge, monitor event bus
+- Monitor (`monitor/`): React + Pixi.js GUI
+
+## Testing
+
+```bash
+npm test              # unit + component + integration
+npm run test:e2e      # E2E (requires ANTHROPIC_API_KEY)
+```
+
+## License
+
+MIT

package/dist/a2a-server.d.ts

@@ -0,0 +1,14 @@
+import { type Express } from 'express';
+import type { AgentRegistry } from './agent-registry.js';
+import type { MonitorBus } from './monitor-bus.js';
+export interface A2AServerOptions {
+    registry: AgentRegistry;
+    singleAgent?: string;
+    port?: number;
+    monitorBus?: MonitorBus;
+}
+export interface A2AServerHandle {
+    app: Express;
+    close: () => Promise<void>;
+}
+export declare function createA2AServer(opts: A2AServerOptions): A2AServerHandle;

package/dist/a2a-server.js

@@ -0,0 +1,44 @@
+// src/a2a-server.ts
+import express from 'express';
+import { DefaultRequestHandler, InMemoryTaskStore, } from '@a2a-js/sdk/server';
+import { agentCardHandler, jsonRpcHandler, UserBuilder, } from '@a2a-js/sdk/server/express';
+import { AGENT_CARD_PATH } from '@a2a-js/sdk';
+import { DojoAgentExecutor } from './agent-executor.js';
+export function createA2AServer(opts) {
+    const app = express();
+    app.use(express.json());
+    const agents = opts.singleAgent
+        ? [opts.registry.get(opts.singleAgent)].filter((a) => a !== undefined)
+        : opts.registry.list().map((id) => opts.registry.get(id)).filter((a) => a !== undefined);
+    for (const loaded of agents) {
+        const card = {
+            name: loaded.manifest.name,
+            description: loaded.manifest.description,
+            url: `http://localhost:${opts.port ?? 41241}/a2a/${loaded.manifest.id}`,
+            version: loaded.manifest.version,
+            protocolVersion: '1.0',
+            capabilities: {
+                streaming: true,
+                pushNotifications: false,
+                stateTransitionHistory: true,
+            },
+            defaultInputModes: ['text'],
+            defaultOutputModes: ['text'],
+            skills: (loaded.manifest.a2aCard?.skills ?? []),
+        };
+        const taskStore = new InMemoryTaskStore();
+        const executor = new DojoAgentExecutor(loaded, { monitorBus: opts.monitorBus });
+        const requestHandler = new DefaultRequestHandler(card, taskStore, executor);
+        const userBuilder = UserBuilder.noAuthentication;
+        app.use(`/a2a/${loaded.manifest.id}`, jsonRpcHandler({ requestHandler, userBuilder }));
+        app.use(`/a2a/${loaded.manifest.id}${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: requestHandler }));
+        app.use(`/a2a/${loaded.manifest.id}/card`, agentCardHandler({ agentCardProvider: requestHandler }));
+    }
+    return {
+        app,
+        close: () => new Promise((resolve) => {
+            // No actual server here; createServer() handles listening
+            resolve();
+        }),
+    };
+}

package/dist/agent-executor.d.ts

@@ -0,0 +1,15 @@
+import type { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
+import type { MonitorBus } from './monitor-bus.js';
+import type { LoadedAgent } from './types.js';
+export interface AgentExecutorOptions {
+    monitorBus?: MonitorBus;
+}
+export declare class DojoAgentExecutor implements AgentExecutor {
+    private agent;
+    private options;
+    private controllers;
+    private contextIds;
+    constructor(agent: LoadedAgent, options?: AgentExecutorOptions);
+    cancelTask: (taskId: string, eventBus: ExecutionEventBus) => Promise<void>;
+    execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+}

package/dist/agent-executor.js

@@ -0,0 +1,147 @@
+// src/agent-executor.ts
+import { v4 as uuidv4 } from 'uuid';
+import { a2aToContentBlocks } from './part-mapper.js';
+import { runClaude } from './claude-bridge.js';
+import { createTranslator } from './event-translator.js';
+import { recordTaskStart, recordTaskEnd } from './metrics.js';
+export class DojoAgentExecutor {
+    agent;
+    options;
+    controllers = new Map();
+    contextIds = new Map();
+    constructor(agent, options = {}) {
+        this.agent = agent;
+        this.options = options;
+    }
+    cancelTask = async (taskId, eventBus) => {
+        const controller = this.controllers.get(taskId);
+        if (!controller)
+            return;
+        const contextId = this.contextIds.get(taskId);
+        controller.abort();
+        this.controllers.delete(taskId);
+        this.contextIds.delete(taskId);
+        // Publish canceled state to the bus so the client sees the transition.
+        // Guard against publishing if the bus is no longer accepting (best-effort).
+        try {
+            eventBus.publish({
+                kind: 'status-update',
+                taskId,
+                contextId,
+                status: {
+                    state: 'canceled',
+                    timestamp: new Date().toISOString(),
+                },
+                final: true,
+            });
+            eventBus.finished();
+        }
+        catch {
+            // ignore — the SDK subprocess may already be torn down
+        }
+    };
+    async execute(requestContext, eventBus) {
+        const { taskId, contextId, userMessage } = requestContext;
+        recordTaskStart();
+        // Publish the initial task snapshot. The A2A SDK's ResultManager only
+        // initializes its currentTask from a `kind: 'task'` event; without it,
+        // subsequent status-update / artifact-update events are dropped as
+        // "unknown task" and the SDK reports "no task context found".
+        eventBus.publish({
+            kind: 'task',
+            id: taskId,
+            contextId,
+            status: {
+                state: 'submitted',
+                timestamp: new Date().toISOString(),
+            },
+            history: [userMessage],
+            artifacts: [],
+        });
+        // Emit task_created to monitor bus. A2A has no real "sender" concept beyond
+        // user/agent, so we use the convention from: 'user' for any inbound client.
+        this.options.monitorBus?.emit({
+            type: 'task_created',
+            taskId,
+            contextId,
+            from: 'user',
+            to: this.agent.manifest.id,
+            preview: extractPreview(userMessage.parts),
+        });
+        // 1. Extract text content from A2A message
+        const parts = userMessage.parts;
+        const contentBlocks = a2aToContentBlocks(parts);
+        // 2. Set up event translator
+        const translator = createTranslator({
+            agentId: this.agent.manifest.id,
+            taskId,
+            contextId,
+            bus: eventBus,
+            monitorBus: this.options.monitorBus,
+        });
+        // 3. Wire up cancellation: each task gets its own AbortController. We pass
+        //    it to the SDK so abort() can tear down the subprocess, and we keep a
+        //    reference so cancelTask() can find it by taskId.
+        const controller = new AbortController();
+        this.controllers.set(taskId, controller);
+        this.contextIds.set(taskId, contextId);
+        // 4. Run Claude (iterate events)
+        try {
+            for await (const sdkMsg of runClaude({
+                agent: this.agent,
+                contentBlocks,
+                contextId,
+                onEvent: (m) => translator.onSdkEvent(m),
+                abortController: controller,
+            })) {
+                // events are published via onEvent
+            }
+            recordTaskEnd(true);
+        }
+        catch (err) {
+            recordTaskEnd(false);
+            // If the controller was aborted, the SDK throws an AbortError. We don't
+            // want to report it as a generic failure — cancelTask already published
+            // the canceled state. Suppress the publish in that case.
+            const isAbort = controller.signal.aborted || (err instanceof Error && /abort/i.test(err.message));
+            if (!isAbort) {
+                // SDK subprocess crash, network failure, etc.
+                const reason = err instanceof Error ? err.message : String(err);
+                eventBus.publish({
+                    kind: 'status-update',
+                    taskId,
+                    contextId,
+                    status: {
+                        state: 'failed',
+                        message: {
+                            kind: 'message',
+                            role: 'agent',
+                            messageId: uuidv4(),
+                            parts: [{ kind: 'text', text: `Subprocess error: ${reason}` }],
+                            taskId,
+                            contextId,
+                        },
+                        timestamp: new Date().toISOString(),
+                    },
+                    final: true,
+                });
+                eventBus.finished();
+            }
+        }
+        finally {
+            this.controllers.delete(taskId);
+            this.contextIds.delete(taskId);
+        }
+    }
+}
+function extractPreview(parts) {
+    if (!Array.isArray(parts))
+        return '';
+    for (const p of parts) {
+        if (p && typeof p === 'object' && p.kind === 'text' && typeof p.text === 'string') {
+            const t = p.text;
+            return t.length > 80 ? t.slice(0, 80) + '…' : t;
+        }
+    }
+    return '';
+}

package/dist/agent-loader.d.ts

@@ -0,0 +1,8 @@
+import type { LoadedAgent } from './types.js';
+export declare class AgentLoadError extends Error {
+    agentDir: string;
+    cause?: unknown | undefined;
+    constructor(agentDir: string, message: string, cause?: unknown | undefined);
+}
+export declare function loadAgent(agentDir: string): LoadedAgent;
+export declare function loadAgents(agentsDir: string): Map<string, LoadedAgent>;

package/dist/agent-loader.js

@@ -0,0 +1,89 @@
+// src/agent-loader.ts
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
+import { join, resolve, isAbsolute } from 'path';
+import stripJsonComments from 'strip-json-comments';
+import { AgentManifestSchema } from './manifest-schema.js';
+import { loadContext } from './context-manager.js';
+export class AgentLoadError extends Error {
+    agentDir;
+    cause;
+    constructor(agentDir, message, cause) {
+        super(`[${agentDir}] ${message}`);
+        this.agentDir = agentDir;
+        this.cause = cause;
+        this.name = 'AgentLoadError';
+    }
+}
+/** Resolve the manifest file path. Prefers `.jsonc`, falls back to `.json`. */
+function resolveManifestPath(agentDir) {
+    const jsonc = join(agentDir, 'manifest.jsonc');
+    if (existsSync(jsonc))
+        return jsonc;
+    const json = join(agentDir, 'manifest.json');
+    if (existsSync(json))
+        return json;
+    return undefined;
+}
+function loadManifest(agentDir) {
+    const path = resolveManifestPath(agentDir);
+    if (!path) {
+        throw new AgentLoadError(agentDir, 'manifest.jsonc (or manifest.json) not found');
+    }
+    const raw = JSON.parse(stripJsonComments(readFileSync(path, 'utf-8')));
+    const result = AgentManifestSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map(i => `  - ${i.path.join('.')}: ${i.message}`).join('\n');
+        throw new AgentLoadError(agentDir, `invalid manifest:\n${issues}`);
+    }
+    return result.data;
+}
+function resolveRef(agentDir, relPath) {
+    if (!relPath)
+        return undefined;
+    const abs = isAbsolute(relPath) ? relPath : join(agentDir, relPath);
+    if (!existsSync(abs)) {
+        throw new AgentLoadError(agentDir, `referenced file not found: ${relPath} (resolved to ${abs})`);
+    }
+    return abs;
+}
+export function loadAgent(agentDir) {
+    const manifest = loadManifest(agentDir);
+    const fixedContextContent = loadContext(agentDir, manifest.fixedContext);
+    return {
+        manifest,
+        agentDir,
+        fixedContextContent,
+        mcpServersPath: resolveRef(agentDir, manifest.mcpServers),
+        hooksPath: resolveRef(agentDir, manifest.hooks),
+        settingsPath: resolveRef(agentDir, manifest.settings),
+        agentsPath: resolveRef(agentDir, manifest.agents),
+        sandboxPath: resolveRef(agentDir, manifest.sandbox),
+    };
+}
+export function loadAgents(agentsDir) {
+    const result = new Map();
+    const absDir = resolve(agentsDir);
+    if (!existsSync(absDir))
+        return result;
+    for (const name of readdirSync(absDir)) {
+        // skip templates and scaffolds: underscore-prefixed directories are not loaded as agents
+        if (name.startsWith('_'))
+            continue;
+        const path = join(absDir, name);
+        if (!statSync(path).isDirectory())
+            continue;
+        if (!resolveManifestPath(path))
+            continue;
+        try {
+            const agent = loadAgent(path);
+            if (result.has(agent.manifest.id)) {
+                throw new Error(`Duplicate agent id "${agent.manifest.id}"`);
+            }
+            result.set(agent.manifest.id, agent);
+        }
+        catch (err) {
+            console.error(`[agent-loader] Failed to load ${name}:`, err instanceof Error ? err.message : err);
+        }
+    }
+    return result;
+}

package/dist/agent-registry.d.ts

@@ -0,0 +1,20 @@
+import { EventEmitter } from 'events';
+import type { LoadedAgent } from './types.js';
+export type ReloadErrorCode = 'not_found' | 'load_error';
+export type ReloadResult = {
+    ok: true;
+    agent: LoadedAgent;
+} | {
+    ok: false;
+    code: ReloadErrorCode;
+    message: string;
+};
+export declare class AgentRegistry extends EventEmitter {
+    private agentsDir;
+    private agents;
+    constructor(agentsDir: string);
+    load(): void;
+    list(): string[];
+    get(id: string): LoadedAgent | undefined;
+    reload(id: string): ReloadResult;
+}

package/dist/agent-registry.js

@@ -0,0 +1,39 @@
+// src/agent-registry.ts
+import { EventEmitter } from 'events';
+import { loadAgent, loadAgents } from './agent-loader.js';
+export class AgentRegistry extends EventEmitter {
+    agentsDir;
+    agents = new Map();
+    constructor(agentsDir) {
+        super();
+        this.agentsDir = agentsDir;
+    }
+    load() {
+        this.agents = loadAgents(this.agentsDir);
+        for (const [id, agent] of this.agents) {
+            this.emit('agent_loaded', { agentId: id, position: agent.manifest.monitor?.position });
+        }
+    }
+    list() {
+        return Array.from(this.agents.keys()).sort();
+    }
+    get(id) {
+        return this.agents.get(id);
+    }
+    reload(id) {
+        const existing = this.agents.get(id);
+        if (!existing) {
+            return { ok: false, code: 'not_found', message: `Agent "${id}" not found` };
+        }
+        try {
+            const updated = loadAgent(existing.agentDir);
+            this.agents.set(id, updated);
+            this.emit('agent_reloaded', { agentId: id });
+            return { ok: true, agent: updated };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { ok: false, code: 'load_error', message: msg };
+        }
+    }
+}

package/dist/claude-bridge.d.ts

@@ -0,0 +1,11 @@
+import { type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { LoadedAgent } from './types.js';
+import type { AnthropicContentBlock } from './part-mapper.js';
+export interface RunClaudeParams {
+    agent: LoadedAgent;
+    contentBlocks: AnthropicContentBlock[];
+    contextId: string;
+    onEvent: (event: SDKMessage) => void;
+    abortController?: AbortController;
+}
+export declare function runClaude(params: RunClaudeParams): AsyncGenerator<SDKMessage>;

package/dist/claude-bridge.js

@@ -0,0 +1,124 @@
+// src/claude-bridge.ts
+import { join } from 'path';
+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;
+    const env = {
+        ...(m.env ?? {}),
+    };
+    // Only override CLAUDE_CONFIG_DIR if the user explicitly specified configDir.
+    // Otherwise, let the subprocess inherit the parent's config (preserving auth).
+    if (m.configDir) {
+        env.CLAUDE_CONFIG_DIR = m.configDir.startsWith('/')
+            ? m.configDir
+            : join(agent.agentDir, m.configDir);
+    }
+    // Build options. Note: we do NOT pass `resume: contextId` here — the Claude
+    // SDK treats resume as a previously-issued session ID, and A2A's contextId
+    // is a fresh UUID with no corresponding SDK session. Treating every send
+    // as a brand-new Claude session is the safe default. (Future: persist a
+    // contextId→sessionId mapping if cross-call continuity is required.)
+    const options = {
+        systemPrompt,
+        cwd: agent.agentDir,
+        env,
+    };
+    if (abortController) {
+        options.abortController = abortController;
+    }
+    if (m.model)
+        options.model = m.model;
+    if (m.fallbackModel)
+        options.fallbackModel = m.fallbackModel;
+    if (m.executable)
+        options.executable = m.executable;
+    if (m.executableArgs)
+        options.executableArgs = m.executableArgs;
+    if (m.pathToClaudeCodeExecutable)
+        options.pathToClaudeCodeExecutable = m.pathToClaudeCodeExecutable;
+    if (m.extraArgs)
+        options.extraArgs = m.extraArgs;
+    if (m.tools)
+        options.tools = m.tools;
+    if (m.allowedTools)
+        options.allowedTools = m.allowedTools;
+    if (m.disallowedTools)
+        options.disallowedTools = m.disallowedTools;
+    if (m.toolAliases)
+        options.toolAliases = m.toolAliases;
+    if (m.permissionMode)
+        options.permissionMode = m.permissionMode;
+    if (m.planModeInstructions)
+        options.planModeInstructions = m.planModeInstructions;
+    if (m.allowDangerouslySkipPermissions !== undefined)
+        options.allowDangerouslySkipPermissions = m.allowDangerouslySkipPermissions;
+    if (m.permissionPromptToolName)
+        options.permissionPromptToolName = m.permissionPromptToolName;
+    if (m.strictMcpConfig !== undefined)
+        options.strictMcpConfig = m.strictMcpConfig;
+    if (m.additionalDirectories)
+        options.additionalDirectories = m.additionalDirectories;
+    if (m.includeHookEvents !== undefined)
+        options.includeHookEvents = m.includeHookEvents;
+    if (m.skills)
+        options.skills = m.skills;
+    if (m.settingSources)
+        options.settingSources = m.settingSources;
+    if (m.thinking)
+        options.thinking = m.thinking;
+    if (m.effort)
+        options.effort = m.effort;
+    if (m.maxThinkingTokens !== undefined)
+        options.maxThinkingTokens = m.maxThinkingTokens;
+    if (m.maxTurns !== undefined)
+        options.maxTurns = m.maxTurns;
+    if (m.maxBudgetUsd !== undefined)
+        options.maxBudgetUsd = m.maxBudgetUsd;
+    if (m.taskBudget)
+        options.taskBudget = m.taskBudget;
+    if (m.betas)
+        options.betas = m.betas;
+    if (m.outputFormat)
+        options.outputFormat = m.outputFormat;
+    if (m.forkSession !== undefined)
+        options.forkSession = m.forkSession;
+    if (agent.agentsPath)
+        options.agents = agent.agentsPath;
+    if (m.agent)
+        options.agent = m.agent;
+    if (m.agentProgressSummaries !== undefined)
+        options.agentProgressSummaries = m.agentProgressSummaries;
+    if (m.forwardSubagentText !== undefined)
+        options.forwardSubagentText = m.forwardSubagentText;
+    if (m.plugins)
+        options.plugins = m.plugins;
+    if (agent.settingsPath)
+        options.settings = agent.settingsPath;
+    // Load MCP servers from file if path is set
+    if (agent.mcpServersPath) {
+        const { readFileSync } = await import('fs');
+        options.mcpServers = JSON.parse(readFileSync(agent.mcpServersPath, 'utf-8'));
+    }
+    // Load hooks from file if path is set
+    if (agent.hooksPath) {
+        const { readFileSync } = await import('fs');
+        options.hooks = JSON.parse(readFileSync(agent.hooksPath, 'utf-8'));
+    }
+    // Build async iterable prompt
+    async function* promptIterable() {
+        yield {
+            type: 'user',
+            message: { role: 'user', content: contentBlocks },
+            parent_tool_use_id: null,
+        };
+    }
+    const q = query({ prompt: promptIterable(), options });
+    for await (const msg of q) {
+        onEvent(msg);
+        yield msg;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+interface Args {
+    agentsDir: string;
+    port: number;
+    monitorPort: number | null;
+    singleAgent: string | null;
+    help: boolean;
+}
+export declare const DEFAULT_ARGS: Args;
+export {};