agentshire 1.0.0

package/src/plugin/group-discussion.ts

@@ -0,0 +1,223 @@
+/**
+ * Group discussion orchestrator.
+ * Manages a round-robin discussion between multiple citizen agents around a user-provided topic.
+ *
+ * Flow:
+ *   1. User provides topic + list of npcIds
+ *   2. Orchestrator sends contextual message to first citizen via routeCitizenMessage
+ *   3. On citizen response (captured via hook), appends to shared history, sends to next citizen
+ *   4. User can "interject" at any time — message is queued and injected after current speaker
+ *   5. Continues until explicitly ended
+ */
+
+import { routeCitizenMessage } from "./citizen-chat-router.js";
+
+const TURN_TIMEOUT_MS = 30_000;
+const MAX_TOTAL_TURNS = 30;
+
+interface Participant {
+  npcId: string;
+  name: string;
+}
+
+interface HistoryEntry {
+  speaker: string;
+  text: string;
+}
+
+interface ActiveDiscussion {
+  participants: Participant[];
+  history: HistoryEntry[];
+  queue: number[];
+  currentIndex: number;
+  currentSpeakerNpcId: string | null;
+  turnTimer: ReturnType<typeof setTimeout> | null;
+  pendingUserMessages: string[];
+  totalTurns: number;
+  stopped: boolean;
+  townSessionId: string;
+  accountId: string;
+  cfg: Record<string, unknown>;
+  responseBuffer: string;
+}
+
+let activeDiscussion: ActiveDiscussion | null = null;
+
+export function hasActiveDiscussion(): boolean {
+  return activeDiscussion !== null && !activeDiscussion.stopped;
+}
+
+export function getDiscussionSpeaker(): string | null {
+  return activeDiscussion?.currentSpeakerNpcId ?? null;
+}
+
+export function startDiscussion(params: {
+  participants: Participant[];
+  townSessionId: string;
+  accountId: string;
+  cfg: Record<string, unknown>;
+}): void {
+  if (activeDiscussion && !activeDiscussion.stopped) {
+    endDiscussion();
+  }
+
+  const { participants, townSessionId, accountId, cfg } = params;
+  const queue = participants.map((_, i) => i);
+
+  activeDiscussion = {
+    participants,
+    history: [],
+    queue,
+    currentIndex: 0,
+    currentSpeakerNpcId: null,
+    turnTimer: null,
+    pendingUserMessages: [],
+    totalTurns: 0,
+    stopped: false,
+    townSessionId,
+    accountId,
+    cfg,
+    responseBuffer: "",
+  };
+
+  console.log(`[group-discussion] Started with ${participants.length} participants: ${participants.map(p => p.name).join(", ")}`);
+}
+
+export function onUserMessage(message: string): void {
+  if (!activeDiscussion || activeDiscussion.stopped) return;
+
+  if (activeDiscussion.currentSpeakerNpcId) {
+    activeDiscussion.pendingUserMessages.push(message);
+    console.log(`[group-discussion] User message queued (speaker active): "${message.slice(0, 50)}"`);
+  } else {
+    activeDiscussion.history.push({ speaker: "镇长", text: message });
+    console.log(`[group-discussion] User message added to history: "${message.slice(0, 50)}"`);
+    sendToNextSpeaker();
+  }
+}
+
+export function onCitizenResponse(agentId: string, text: string): void {
+  if (!activeDiscussion || activeDiscussion.stopped) return;
+
+  const participant = activeDiscussion.participants.find(p => {
+    const expectedPrefix = `citizen-${p.npcId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+    return agentId === expectedPrefix || agentId === p.npcId;
+  });
+
+  if (!participant) return;
+  if (participant.npcId !== activeDiscussion.currentSpeakerNpcId) return;
+
+  activeDiscussion.responseBuffer += text;
+}
+
+export function onCitizenTurnEnd(agentId: string): void {
+  if (!activeDiscussion || activeDiscussion.stopped) return;
+
+  const participant = activeDiscussion.participants.find(p => {
+    const expectedPrefix = `citizen-${p.npcId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+    return agentId === expectedPrefix || agentId === p.npcId;
+  });
+
+  if (!participant) return;
+  if (participant.npcId !== activeDiscussion.currentSpeakerNpcId) return;
+
+  if (activeDiscussion.turnTimer) {
+    clearTimeout(activeDiscussion.turnTimer);
+    activeDiscussion.turnTimer = null;
+  }
+
+  const responseText = activeDiscussion.responseBuffer.trim();
+  activeDiscussion.responseBuffer = "";
+  activeDiscussion.currentSpeakerNpcId = null;
+
+  if (responseText) {
+    activeDiscussion.history.push({ speaker: participant.name, text: responseText });
+    console.log(`[group-discussion] ${participant.name} said: "${responseText.slice(0, 80)}"`);
+  } else {
+    console.log(`[group-discussion] ${participant.name} had empty response, skipping`);
+  }
+
+  if (activeDiscussion.stopped) return;
+
+  while (activeDiscussion.pendingUserMessages.length > 0) {
+    const userMsg = activeDiscussion.pendingUserMessages.shift()!;
+    activeDiscussion.history.push({ speaker: "镇长", text: userMsg });
+    console.log(`[group-discussion] Flushed queued user message: "${userMsg.slice(0, 50)}"`);
+  }
+
+  activeDiscussion.currentIndex = (activeDiscussion.currentIndex + 1) % activeDiscussion.participants.length;
+
+  sendToNextSpeaker();
+}
+
+export function endDiscussion(): void {
+  if (!activeDiscussion) return;
+
+  console.log(`[group-discussion] Ending discussion (${activeDiscussion.totalTurns} total turns)`);
+
+  activeDiscussion.stopped = true;
+  if (activeDiscussion.turnTimer) {
+    clearTimeout(activeDiscussion.turnTimer);
+    activeDiscussion.turnTimer = null;
+  }
+  activeDiscussion = null;
+}
+
+function buildContextMessage(discussion: ActiveDiscussion): string {
+  let context = "";
+  for (const entry of discussion.history) {
+    context += `${entry.speaker}：${entry.text}\n`;
+  }
+  context += `\n轮到你了，简短回复。`;
+
+  return context;
+}
+
+function sendToNextSpeaker(): void {
+  if (!activeDiscussion || activeDiscussion.stopped) return;
+
+  if (activeDiscussion.totalTurns >= MAX_TOTAL_TURNS) {
+    console.log(`[group-discussion] Max turns (${MAX_TOTAL_TURNS}) reached, pausing`);
+    return;
+  }
+
+  if (activeDiscussion.history.length === 0) return;
+
+  const participant = activeDiscussion.participants[activeDiscussion.currentIndex];
+  const contextMessage = buildContextMessage(activeDiscussion);
+
+  activeDiscussion.currentSpeakerNpcId = participant.npcId;
+  activeDiscussion.responseBuffer = "";
+  activeDiscussion.totalTurns++;
+
+  console.log(`[group-discussion] Turn ${activeDiscussion.totalTurns}: sending to ${participant.name} (${participant.npcId})`);
+
+  activeDiscussion.turnTimer = setTimeout(() => {
+    if (!activeDiscussion || activeDiscussion.currentSpeakerNpcId !== participant.npcId) return;
+    console.log(`[group-discussion] ${participant.name} timed out after ${TURN_TIMEOUT_MS}ms, skipping`);
+    activeDiscussion.currentSpeakerNpcId = null;
+    activeDiscussion.responseBuffer = "";
+    activeDiscussion.currentIndex = (activeDiscussion.currentIndex + 1) % activeDiscussion.participants.length;
+    sendToNextSpeaker();
+  }, TURN_TIMEOUT_MS);
+
+  routeCitizenMessage({
+    npcId: participant.npcId,
+    label: participant.name,
+    message: contextMessage,
+    townSessionId: activeDiscussion.townSessionId,
+    accountId: activeDiscussion.accountId,
+    cfg: activeDiscussion.cfg,
+  }).catch((err) => {
+    console.error(`[group-discussion] Failed to route message to ${participant.name}:`, err);
+    if (!activeDiscussion || activeDiscussion.stopped) return;
+    if (activeDiscussion.turnTimer) {
+      clearTimeout(activeDiscussion.turnTimer);
+      activeDiscussion.turnTimer = null;
+    }
+    activeDiscussion.currentSpeakerNpcId = null;
+    activeDiscussion.responseBuffer = "";
+    activeDiscussion.currentIndex = (activeDiscussion.currentIndex + 1) % activeDiscussion.participants.length;
+    sendToNextSpeaker();
+  });
+}

package/src/plugin/hook-translator.ts

@@ -0,0 +1,202 @@
+import type { AgentEvent } from "../contracts/events.js";
+import type { ContentKind } from "../contracts/media.js";
+import { readFileSync, existsSync } from "node:fs";
+
+function tryReadBase64(filePath: string): string | undefined {
+  try {
+    if (!filePath || !existsSync(filePath)) return undefined;
+    return readFileSync(filePath).toString('base64');
+  } catch { return undefined; }
+}
+
+let sessionCounter = 0;
+
+const MEDIA_EXTENSIONS = new Set([
+  "png", "jpg", "jpeg", "gif", "webp", "svg", "bmp",
+  "mp4", "webm", "mov", "avi", "mkv",
+  "mp3", "wav", "ogg", "m4a", "flac",
+  "pdf", "zip", "tar", "gz",
+]);
+
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp"]);
+const VIDEO_EXTENSIONS = new Set(["mp4", "webm", "mov", "avi", "mkv"]);
+const AUDIO_EXTENSIONS = new Set(["mp3", "wav", "ogg", "m4a", "flac"]);
+
+function detectMediaKind(ext: string): ContentKind {
+  if (IMAGE_EXTENSIONS.has(ext)) return "image";
+  if (VIDEO_EXTENSIONS.has(ext)) return "video";
+  if (AUDIO_EXTENSIONS.has(ext)) return "audio";
+  return "file";
+}
+
+function extractMediaPath(toolName: string, params: any, result: any): string | null {
+  if (toolName === "image") {
+    const output = String(result ?? "");
+    const match = output.match(/(?:saved|wrote|created|generated)[^"]*?["']?([^\s"']+\.(?:png|jpg|jpeg|gif|webp))/i);
+    if (match) return match[1];
+    const pathMatch = output.match(/\/[^\s"']+\.(?:png|jpg|jpeg|gif|webp)/i);
+    if (pathMatch) return pathMatch[0];
+    return params?.path ?? params?.output_path ?? null;
+  }
+
+  if (toolName === "exec" || toolName === "bash") {
+    const cmd = String(params?.command ?? "");
+    if (/screencapture|screenshot/i.test(cmd)) {
+      const pathMatch = cmd.match(/[\w/.-]+\.(?:png|jpg|jpeg|gif)/i);
+      if (pathMatch) return pathMatch[0];
+    }
+  }
+
+  const output = String(result ?? "");
+  const fileMatch = output.match(/\/[^\s"']+\.(\w+)/);
+  if (fileMatch && MEDIA_EXTENSIONS.has(fileMatch[1].toLowerCase())) {
+    return fileMatch[0];
+  }
+
+  return null;
+}
+
+export function hookToAgentEvent(
+  hookName: string,
+  payload: Record<string, unknown>,
+): AgentEvent | AgentEvent[] | null {
+  switch (hookName) {
+    case "before_agent_start":
+      return {
+        type: "system",
+        subtype: "init",
+        sessionId: String(payload.sessionId ?? `oc-session-${++sessionCounter}`),
+        model: String(payload.model ?? "unknown"),
+        persona: payload.persona as string | undefined,
+      };
+
+    case "agent_end": {
+      const events: AgentEvent[] = [];
+
+      if (payload.success === false || payload.error) {
+        events.push({
+          type: "error",
+          message: String(payload.error ?? "Agent run failed"),
+          recoverable: false,
+        });
+      }
+
+      const usage = payload.usage as { inputTokens?: number; outputTokens?: number } | undefined;
+      events.push({
+        type: "turn_end",
+        usage: {
+          inputTokens: usage?.inputTokens ?? 0,
+          outputTokens: usage?.outputTokens ?? 0,
+        },
+        toolCalls: (payload.toolCalls as number) ?? 0,
+        durationMs: (payload.durationMs as number) ?? 0,
+      });
+
+      return events;
+    }
+
+    case "llm_input": {
+      const delta = String(payload.thinking ?? payload.reasoning ?? payload.thought ?? "");
+      return { type: "thinking_delta", delta };
+    }
+
+    case "llm_output": {
+      const texts = payload.assistantTexts as string[] | undefined;
+      const text = texts?.[texts.length - 1] ?? String(payload.text ?? payload.content ?? "");
+      if (!text) return null;
+      return { type: "text", content: text };
+    }
+
+    case "before_tool_call":
+      return {
+        type: "tool_use",
+        toolUseId: String(payload.toolCallId ?? payload.toolUseId ?? `tool-${Date.now()}`),
+        name: String(payload.toolName ?? payload.name ?? "unknown"),
+        input: (payload.params ?? payload.input ?? {}) as Record<string, unknown>,
+      };
+
+    case "after_tool_call": {
+      const toolName = String(payload.toolName ?? payload.name ?? "unknown");
+      const events: AgentEvent[] = [
+        {
+          type: "tool_result",
+          toolUseId: String(payload.toolCallId ?? payload.toolUseId ?? ""),
+          name: toolName,
+          output: String(payload.result ?? payload.output ?? ""),
+          meta: payload.meta as Record<string, unknown> | undefined,
+        },
+      ];
+
+      const mediaPath = extractMediaPath(toolName, payload.params, payload.result);
+      if (mediaPath) {
+        const ext = mediaPath.split(".").pop()?.toLowerCase() ?? "";
+        const mimeMap: Record<string, string> = {
+          png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+          gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+          mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime",
+          mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4",
+        };
+        events.push({
+          type: "media_output",
+          kind: detectMediaKind(ext),
+          path: mediaPath,
+          mimeType: mimeMap[ext] ?? "application/octet-stream",
+          data: tryReadBase64(mediaPath),
+          role: "assistant",
+          meta: { filename: mediaPath.split("/").pop() },
+        });
+      }
+
+      return events;
+    }
+
+    case "subagent_spawned": {
+      const childKey = String(payload.childSessionKey ?? "");
+      const uniqueId = childKey || String(payload.runId ?? `sub-${Date.now()}`);
+      return {
+        type: "sub_agent",
+        subtype: "started",
+        agentId: uniqueId,
+        agentType: String(payload.agentType ?? "worker"),
+        parentToolUseId: String(payload.parentToolUseId ?? ""),
+        task: String(payload.task ?? payload.label ?? ""),
+        model: String(payload.model ?? "unknown"),
+        displayName: (payload.label ?? payload.displayName) as string | undefined,
+      };
+    }
+
+    case "subagent_ended": {
+      const targetKey = String(payload.targetSessionKey ?? "");
+      const endId = targetKey || String(payload.runId ?? payload.agentId ?? "");
+      const outcome = String(payload.outcome ?? "ok");
+      const statusMap: Record<string, string> = {
+        ok: "completed", error: "failed", timeout: "failed", killed: "killed", reset: "killed", deleted: "killed",
+      };
+      return {
+        type: "sub_agent",
+        subtype: "done",
+        agentId: endId,
+        result: String(payload.result ?? payload.reason ?? ""),
+        toolCalls: (payload.toolCalls as number) ?? 0,
+        status: (statusMap[outcome] ?? "completed") as "completed" | "failed" | "killed",
+      };
+    }
+
+    case "message_sending": {
+      const text = String(payload.content ?? payload.text ?? payload.body ?? "");
+      if (!text) return null;
+      return { type: "text", content: text };
+    }
+
+    case "session_end":
+      return {
+        type: "system",
+        subtype: "done",
+        result: "session_end",
+        sessionId: String(payload.sessionId ?? ""),
+      };
+
+    default:
+      return null;
+  }
+}

package/src/plugin/llm-agent-proxy.ts

@@ -0,0 +1,193 @@
+/**
+ * LLM proxy for implicit NPC behaviors and soul generation.
+ * Reads provider config from OpenClaw runtime (rt.config.loadConfig()),
+ * resolves env-templated API keys from the config's env section,
+ * and makes direct HTTP calls. Falls back to process.env for QClaw compatibility.
+ */
+
+import { getTownRuntime } from "./runtime.js";
+
+export interface LLMChatRequest {
+  system: string;
+  user: string;
+  maxTokens: number;
+  temperature: number;
+  stop: string[];
+}
+
+export interface LLMChatResult {
+  text: string;
+  usage?: { input: number; output: number };
+}
+
+interface ProviderConfig {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  apiFormat: "anthropic-messages" | "openai";
+}
+
+const MAX_CONCURRENT = 2;
+const MAX_QUEUE = 10;
+
+function resolveEnvRef(value: string, env: Record<string, string>): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, key) => env[key] ?? process.env[key] ?? "");
+}
+
+function loadProvider(): ProviderConfig | null {
+  try {
+    const rt = getTownRuntime();
+    const cfg = rt.config.loadConfig() as any;
+    const env: Record<string, string> = cfg?.env ?? {};
+    const providers = cfg?.models?.providers;
+    if (!providers || typeof providers !== "object") return null;
+
+    for (const [, provider] of Object.entries(providers) as [string, any][]) {
+      if (!provider.baseUrl || !provider.apiKey) continue;
+      const apiKey = resolveEnvRef(String(provider.apiKey), env);
+      if (!apiKey) continue;
+
+      const apiFormat = provider.api?.startsWith("openai") ? "openai" as const : "anthropic-messages" as const;
+      const models = Array.isArray(provider.models) ? provider.models : [];
+      const model = models[0]?.id ?? "default";
+
+      return {
+        baseUrl: String(provider.baseUrl).replace(/\/+$/, ""),
+        apiKey,
+        model,
+        apiFormat,
+      };
+    }
+  } catch (err) {
+    console.warn("[llm-agent-proxy] Failed to load provider:", (err as Error).message);
+  }
+  return null;
+}
+
+async function callAnthropicMessages(config: ProviderConfig, req: LLMChatRequest): Promise<LLMChatResult> {
+  const body = {
+    model: config.model,
+    max_tokens: req.maxTokens,
+    temperature: req.temperature,
+    system: req.system,
+    messages: [{ role: "user", content: req.user }],
+    ...(req.stop.length > 0 ? { stop_sequences: req.stop } : {}),
+  };
+
+  const url = `${config.baseUrl}/v1/messages`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": config.apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!resp.ok) {
+    const errText = await resp.text().catch(() => "");
+    throw new Error(`Anthropic API ${resp.status}: ${errText.slice(0, 200)}`);
+  }
+
+  const data = await resp.json() as {
+    content?: Array<{ type: string; text?: string }>;
+    usage?: { input_tokens?: number; output_tokens?: number };
+  };
+
+  const text = data.content?.find(b => b.type === "text")?.text ?? "";
+  return {
+    text,
+    usage: data.usage
+      ? { input: data.usage.input_tokens ?? 0, output: data.usage.output_tokens ?? 0 }
+      : undefined,
+  };
+}
+
+async function callOpenAI(config: ProviderConfig, req: LLMChatRequest): Promise<LLMChatResult> {
+  const body = {
+    model: config.model,
+    max_tokens: req.maxTokens,
+    temperature: req.temperature,
+    messages: [
+      { role: "system", content: req.system },
+      { role: "user", content: req.user },
+    ],
+    ...(req.stop.length > 0 ? { stop: req.stop } : {}),
+  };
+
+  const url = `${config.baseUrl}/v1/chat/completions`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!resp.ok) {
+    const errText = await resp.text().catch(() => "");
+    throw new Error(`OpenAI API ${resp.status}: ${errText.slice(0, 200)}`);
+  }
+
+  const data = await resp.json() as {
+    choices?: Array<{ message?: { content?: string } }>;
+    usage?: { prompt_tokens?: number; completion_tokens?: number };
+  };
+
+  const text = data.choices?.[0]?.message?.content ?? "";
+  return {
+    text,
+    usage: data.usage
+      ? { input: data.usage.prompt_tokens ?? 0, output: data.usage.completion_tokens ?? 0 }
+      : undefined,
+  };
+}
+
+let activeRequests = 0;
+const requestQueue: Array<{
+  req: LLMChatRequest;
+  resolve: (r: LLMChatResult) => void;
+  reject: (e: Error) => void;
+}> = [];
+
+function drainQueue(): void {
+  if (requestQueue.length === 0 || activeRequests >= MAX_CONCURRENT) return;
+  const next = requestQueue.shift()!;
+  executeChat(next.req).then(next.resolve, next.reject);
+}
+
+async function executeChat(req: LLMChatRequest): Promise<LLMChatResult> {
+  activeRequests++;
+  try {
+    const config = loadProvider();
+    if (!config) return { text: "" };
+    return config.apiFormat === "openai"
+      ? await callOpenAI(config, req)
+      : await callAnthropicMessages(config, req);
+  } catch (err) {
+    console.warn("[llm-agent-proxy] chat error:", (err as Error).message);
+    return { text: "" };
+  } finally {
+    activeRequests--;
+    drainQueue();
+  }
+}
+
+export async function chat(req: LLMChatRequest): Promise<LLMChatResult> {
+  if (activeRequests >= MAX_CONCURRENT) {
+    return new Promise<LLMChatResult>((resolve, reject) => {
+      if (requestQueue.length >= MAX_QUEUE) {
+        resolve({ text: "" });
+        return;
+      }
+      requestQueue.push({ req, resolve, reject });
+    });
+  }
+  return executeChat(req);
+}
+
+export function isAvailable(): boolean {
+  return loadProvider() !== null;
+}