agentshire 1.0.0

package/src/bridge/implicit-chat.ts

@@ -0,0 +1,192 @@
+/**
+ * Unified LLM call layer for implicit NPC behavior.
+ * Uses dependency injection for the actual chat function so it works
+ * in both Node.js (direct provider) and browser (WS proxy) environments.
+ */
+
+export type ImplicitScene =
+  | 'daily_plan' | 'tactical_decision' | 'daily_reflection'
+  | 'encounter_init' | 'encounter_reply' | 'dialogue_summary'
+  | 'town_journal'
+  | 'task_assign' | 'work_thought' | 'supervision_comment'
+
+export interface ImplicitChatRequest {
+  scene: ImplicitScene
+  system: string
+  user: string
+  /** Override per-scene maxTokens */
+  maxTokens?: number
+  /** Override default temperature */
+  temperature?: number
+  /** Extra stop sequences appended to defaults */
+  extraStop?: string[]
+}
+
+export interface ImplicitChatResult {
+  text: string
+  latencyMs: number
+  tokenUsage?: { input: number; output: number }
+  fallback: boolean
+}
+
+export interface ImplicitChatFn {
+  (req: {
+    model: string
+    system: string
+    user: string
+    maxTokens: number
+    temperature: number
+    stop: string[]
+  }): Promise<{
+    text: string
+    usage?: { input: number; output: number }
+  }>
+}
+
+const SCENE_MAX_TOKENS: Record<ImplicitScene, number> = {
+  daily_plan: 200,
+  tactical_decision: 80,
+  daily_reflection: 60,
+  encounter_init: 80,
+  encounter_reply: 80,
+  dialogue_summary: 60,
+  town_journal: 300,
+  task_assign: 100,
+  work_thought: 60,
+  supervision_comment: 80,
+}
+
+const DEFAULT_STOP = ['\n\n']
+
+const FALLBACK: Partial<Record<ImplicitScene, string[]>> = {
+  encounter_init: ['嗨，好久不见！', '哟，你也在这啊', '今天天气不错呢', '嘿！在干嘛呢？'],
+  encounter_reply: ['是呀！', '哈哈对', '嗯嗯', '说得也是', '确实如此'],
+  dialogue_summary: ['闲聊了几句'],
+  daily_reflection: ['今天过得还不错', '充实的一天', '平淡但安心'],
+  daily_plan: [],
+  tactical_decision: [],
+}
+
+function pickFallback(scene: ImplicitScene): string {
+  const pool = FALLBACK[scene]
+  if (!pool || pool.length === 0) return ''
+  return pool[Math.floor(Math.random() * pool.length)]
+}
+
+export interface ImplicitChatConfig {
+  model: string
+  temperature: number
+  timeoutMs: number
+}
+
+const DEFAULT_CONFIG: ImplicitChatConfig = {
+  model: 'qwen-turbo',
+  temperature: 0.85,
+  timeoutMs: 8000,
+}
+
+let _chatFn: ImplicitChatFn | null = null
+let _config: ImplicitChatConfig = { ...DEFAULT_CONFIG }
+
+let _totalCalls = 0
+let _totalTokensIn = 0
+let _totalTokensOut = 0
+let _totalLatencyMs = 0
+let _fallbackCount = 0
+
+export function setImplicitChatFn(fn: ImplicitChatFn): void {
+  _chatFn = fn
+}
+
+export function setImplicitChatConfig(config: Partial<ImplicitChatConfig>): void {
+  _config = { ..._config, ...config }
+}
+
+export function getImplicitChatStats() {
+  return {
+    totalCalls: _totalCalls,
+    totalTokensIn: _totalTokensIn,
+    totalTokensOut: _totalTokensOut,
+    totalLatencyMs: _totalLatencyMs,
+    fallbackCount: _fallbackCount,
+    avgLatencyMs: _totalCalls > 0 ? Math.round(_totalLatencyMs / _totalCalls) : 0,
+  }
+}
+
+export function resetImplicitChatStats(): void {
+  _totalCalls = 0
+  _totalTokensIn = 0
+  _totalTokensOut = 0
+  _totalLatencyMs = 0
+  _fallbackCount = 0
+}
+
+export async function implicitChat(req: ImplicitChatRequest): Promise<ImplicitChatResult> {
+  _totalCalls++
+
+  if (!_chatFn) {
+    _fallbackCount++
+    return {
+      text: pickFallback(req.scene),
+      latencyMs: 0,
+      fallback: true,
+    }
+  }
+
+  const maxTokens = req.maxTokens ?? SCENE_MAX_TOKENS[req.scene]
+  const temperature = req.temperature ?? _config.temperature
+  const stop = [...DEFAULT_STOP, ...(req.extraStop ?? [])]
+
+  const start = performance.now()
+
+  try {
+    const result = await Promise.race([
+      _chatFn({
+        model: _config.model,
+        system: req.system,
+        user: req.user,
+        maxTokens,
+        temperature,
+        stop,
+      }),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('implicit_chat_timeout')), _config.timeoutMs)
+      ),
+    ])
+
+    const latencyMs = Math.round(performance.now() - start)
+    _totalLatencyMs += latencyMs
+
+    const text = (result.text ?? '').trim()
+
+    if (!text) {
+      _fallbackCount++
+      return { text: pickFallback(req.scene), latencyMs, fallback: true }
+    }
+
+    if (result.usage) {
+      _totalTokensIn += result.usage.input
+      _totalTokensOut += result.usage.output
+    }
+
+    return {
+      text,
+      latencyMs,
+      tokenUsage: result.usage,
+      fallback: false,
+    }
+  } catch (err) {
+    const latencyMs = Math.round(performance.now() - start)
+    _totalLatencyMs += latencyMs
+    _fallbackCount++
+
+    const tag = err instanceof Error && err.message === 'implicit_chat_timeout' ? '[timeout]' : '[error]'
+    console.warn(`implicitChat ${tag} scene=${req.scene} ${latencyMs}ms`, err)
+
+    return {
+      text: pickFallback(req.scene),
+      latencyMs,
+      fallback: true,
+    }
+  }
+}

package/src/bridge/index.ts

@@ -0,0 +1,12 @@
+// @desc Bridge layer barrel export — re-exports all bridge modules
+export { EventTranslator } from './EventTranslator.js'
+export { StateTracker } from './StateTracker.js'
+export { ReconnectManager } from './ReconnectManager.js'
+export { DirectorBridge } from './DirectorBridge.js'
+export { NpcEventQueue } from './NpcEventQueue.js'
+export { RouteManager } from './RouteManager.js'
+export { ActivityStream } from './ActivityStream.js'
+export { CitizenManager } from './CitizenManager.js'
+export * from './ToolVfxMapper.js'
+export { implicitChat, setImplicitChatFn, setImplicitChatConfig, getImplicitChatStats, resetImplicitChatStats } from './implicit-chat.js'
+export type { ImplicitScene, ImplicitChatRequest, ImplicitChatResult, ImplicitChatFn, ImplicitChatConfig } from './implicit-chat.js'

package/src/contracts/agent-state.ts

@@ -0,0 +1,87 @@
+// @desc Agent state machine and structured state snapshots
+//
+// AgentStateSnapshot 是递归结构, children 字段形成子代理树
+// 前端可据此渲染实时代理状态面板 (phase → UI 状态, activity → 当前动作)
+//
+// 迁移注意:
+//   - ws-handler 尚未发送 SessionState, 仍用旧的扁平 { sessionId, status }
+//   - state_snapshot AgentEvent 尚未在 OpenClaw 核心中发射
+//   - CLI 的 App.tsx 目前自行拼装子代理树, 未来应改用 AgentStateSnapshot
+
+export type AgentPhase =
+  | 'initializing'
+  | 'idle'
+  | 'thinking'
+  | 'tool_calling'
+  | 'streaming'
+  | 'waiting_input'
+  | 'done'
+  | 'error';
+
+export interface AgentActivity {
+  type: 'llm_call' | 'tool_execution' | 'sub_agent_wait';
+  toolName?: string;
+  toolUseId?: string;
+  description?: string;
+  startedAt: number;
+  progress?: number;
+}
+
+export type HookIcon = '🛡️' | '🔧' | '🛑' | '🗜️' | '🚀' | '🏁' | '🔔';
+
+export interface HookActivity {
+  event: 'PreToolUse' | 'PostToolUse' | 'Stop' | 'PreCompact' | 'SessionStart' | 'SessionEnd' | 'Notification';
+  status: 'running' | 'success' | 'error' | 'blocked';
+  icon: HookIcon;
+  toolName?: string;
+  detail?: string;
+  durationMs?: number;
+}
+
+export const HOOK_ICONS: Record<string, HookIcon> = {
+  PreToolUse: '🛡️',
+  PostToolUse: '🔧',
+  Stop: '🛑',
+  PreCompact: '🗜️',
+  SessionStart: '🚀',
+  SessionEnd: '🏁',
+  Notification: '🔔',
+};
+
+export interface AgentResources {
+  tokens: { used: number; limit: number; percent: number };
+  iteration: { current: number; max: number };
+  durationMs: number;
+}
+
+export interface AgentSnapStats {
+  toolCalls: number;
+  agentSpawns: number;
+  tokensIn: number;
+  tokensOut: number;
+}
+
+export interface AgentStateSnapshot {
+  agentId: string;
+  displayName?: string;
+  phase: AgentPhase;
+  model: string;
+  persona?: string;
+  activity?: AgentActivity;
+  hookActivity?: HookActivity;
+  resources: AgentResources;
+  stats: AgentSnapStats;
+  children: AgentStateSnapshot[];
+}
+
+export type SessionStatus = 'active' | 'suspended' | 'completed' | 'error';
+
+export interface SessionState {
+  sessionId: string;
+  status: SessionStatus;
+  rootAgent: AgentStateSnapshot;
+  createdAt: number;
+  lastActiveAt: number;
+  persona?: string;
+  metadata?: Record<string, unknown>;
+}

package/src/contracts/agui.ts

@@ -0,0 +1,212 @@
+// @desc AGUI (AG-UI Protocol) event types for OpenClaw
+// Based on AG-UI Protocol: https://docs.ag-ui.com/concepts/events
+//
+// These types mirror the AGUI definitions in packages/agentstudio/backend/src/engines/types.ts
+// but live within OpenClaw's contract layer so the package is self-contained.
+
+// ── Event Type Enum ──
+
+export enum AGUIEventType {
+  // Lifecycle
+  RUN_STARTED = 'RUN_STARTED',
+  RUN_FINISHED = 'RUN_FINISHED',
+  RUN_ERROR = 'RUN_ERROR',
+  STEP_STARTED = 'STEP_STARTED',
+  STEP_FINISHED = 'STEP_FINISHED',
+
+  // Text Message
+  TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
+  TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
+  TEXT_MESSAGE_END = 'TEXT_MESSAGE_END',
+
+  // Thinking (extended)
+  THINKING_START = 'THINKING_START',
+  THINKING_CONTENT = 'THINKING_CONTENT',
+  THINKING_END = 'THINKING_END',
+
+  // Tool Call
+  TOOL_CALL_START = 'TOOL_CALL_START',
+  TOOL_CALL_ARGS = 'TOOL_CALL_ARGS',
+  TOOL_CALL_END = 'TOOL_CALL_END',
+  TOOL_CALL_RESULT = 'TOOL_CALL_RESULT',
+
+  // State Management
+  STATE_SNAPSHOT = 'STATE_SNAPSHOT',
+  STATE_DELTA = 'STATE_DELTA',
+  MESSAGES_SNAPSHOT = 'MESSAGES_SNAPSHOT',
+
+  // Special
+  RAW = 'RAW',
+  CUSTOM = 'CUSTOM',
+}
+
+// ── Base Event ──
+
+export interface AGUIBaseEvent {
+  type: AGUIEventType;
+  timestamp: number;
+  threadId?: string;
+  runId?: string;
+}
+
+// ── Lifecycle Events ──
+
+export interface AGUIRunStartedEvent extends AGUIBaseEvent {
+  type: AGUIEventType.RUN_STARTED;
+  threadId: string;
+  runId: string;
+  input?: unknown;
+}
+
+export interface AGUIRunFinishedEvent extends AGUIBaseEvent {
+  type: AGUIEventType.RUN_FINISHED;
+  threadId: string;
+  runId: string;
+  result?: unknown;
+}
+
+export interface AGUIRunErrorEvent extends AGUIBaseEvent {
+  type: AGUIEventType.RUN_ERROR;
+  error: string;
+  code?: string;
+  message?: string;
+}
+
+export interface AGUIStepStartedEvent extends AGUIBaseEvent {
+  type: AGUIEventType.STEP_STARTED;
+  stepName?: string;
+}
+
+export interface AGUIStepFinishedEvent extends AGUIBaseEvent {
+  type: AGUIEventType.STEP_FINISHED;
+  stepName?: string;
+}
+
+// ── Text Message Events ──
+
+export interface AGUITextMessageStartEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TEXT_MESSAGE_START;
+  messageId: string;
+  role?: 'assistant' | 'user' | 'system';
+}
+
+export interface AGUITextMessageContentEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TEXT_MESSAGE_CONTENT;
+  messageId: string;
+  content: string;
+}
+
+export interface AGUITextMessageEndEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TEXT_MESSAGE_END;
+  messageId: string;
+}
+
+// ── Thinking Events ──
+
+export interface AGUIThinkingStartEvent extends AGUIBaseEvent {
+  type: AGUIEventType.THINKING_START;
+  messageId: string;
+}
+
+export interface AGUIThinkingContentEvent extends AGUIBaseEvent {
+  type: AGUIEventType.THINKING_CONTENT;
+  messageId: string;
+  content: string;
+}
+
+export interface AGUIThinkingEndEvent extends AGUIBaseEvent {
+  type: AGUIEventType.THINKING_END;
+  messageId: string;
+}
+
+// ── Tool Call Events ──
+
+export interface AGUIToolCallStartEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TOOL_CALL_START;
+  toolCallId: string;
+  toolName: string;
+  parentMessageId?: string;
+}
+
+export interface AGUIToolCallArgsEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TOOL_CALL_ARGS;
+  toolCallId: string;
+  args: string;
+}
+
+export interface AGUIToolCallEndEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TOOL_CALL_END;
+  toolCallId: string;
+}
+
+export interface AGUIToolCallResultEvent extends AGUIBaseEvent {
+  type: AGUIEventType.TOOL_CALL_RESULT;
+  toolCallId: string;
+  result: string;
+  isError?: boolean;
+}
+
+// ── State Management Events ──
+
+export interface AGUIStateSnapshotEvent extends AGUIBaseEvent {
+  type: AGUIEventType.STATE_SNAPSHOT;
+  snapshot: unknown;
+}
+
+export interface AGUIStateDeltaEvent extends AGUIBaseEvent {
+  type: AGUIEventType.STATE_DELTA;
+  delta: unknown;
+}
+
+export interface AGUIMessagesSnapshotEvent extends AGUIBaseEvent {
+  type: AGUIEventType.MESSAGES_SNAPSHOT;
+  messages: unknown[];
+}
+
+// ── Special Events ──
+
+export interface AGUIRawEvent extends AGUIBaseEvent {
+  type: AGUIEventType.RAW;
+  source: string;
+  event: unknown;
+}
+
+export interface AGUICustomEvent extends AGUIBaseEvent {
+  type: AGUIEventType.CUSTOM;
+  name: string;
+  data: unknown;
+}
+
+// ── Union Type ──
+
+export type AGUIEvent =
+  | AGUIRunStartedEvent
+  | AGUIRunFinishedEvent
+  | AGUIRunErrorEvent
+  | AGUIStepStartedEvent
+  | AGUIStepFinishedEvent
+  | AGUITextMessageStartEvent
+  | AGUITextMessageContentEvent
+  | AGUITextMessageEndEvent
+  | AGUIThinkingStartEvent
+  | AGUIThinkingContentEvent
+  | AGUIThinkingEndEvent
+  | AGUIToolCallStartEvent
+  | AGUIToolCallArgsEvent
+  | AGUIToolCallEndEvent
+  | AGUIToolCallResultEvent
+  | AGUIStateSnapshotEvent
+  | AGUIStateDeltaEvent
+  | AGUIMessagesSnapshotEvent
+  | AGUIRawEvent
+  | AGUICustomEvent;
+
+// ── Utility Functions ──
+
+export function formatAguiEventAsSSE(event: AGUIEvent): string {
+  return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+
+export function createTimestamp(): number {
+  return Date.now();
+}

package/src/contracts/chat.ts

@@ -0,0 +1,67 @@
+/**
+ * ChatItem — Chat 视图的统一消息模型。
+ *
+ * 设计原则：
+ *   1. 唯一事实源是 OpenClaw session transcript（.jsonl）。
+ *   2. 历史恢复和实时增量共用同一套模型。
+ *   3. 不依赖 Town 的 AgentEvent 语义。
+ *   4. 每个 item 有稳定 id，支持跨 history/delta/reload 去重。
+ */
+
+export type ChatMediaType = "image" | "video" | "audio" | "file";
+
+export type ChatItemKind = "text" | "media" | "tool" | "status";
+
+export interface ChatItemBase {
+  id: string;
+  agentId: string;
+  timestamp: number;
+}
+
+export interface ChatTextItem extends ChatItemBase {
+  kind: "text";
+  role: "user" | "assistant";
+  text: string;
+  source?: "user_input" | "llm" | "system";
+}
+
+export interface ChatMediaItem extends ChatItemBase {
+  kind: "media";
+  role: "user" | "assistant";
+  mediaType: ChatMediaType;
+  filePath?: string;
+  fileUrl: string;
+  fileName?: string;
+  mimeType?: string;
+  fileSize?: number;
+  caption?: string;
+  imageData?: string;
+}
+
+export interface ChatToolItem extends ChatItemBase {
+  kind: "tool";
+  phase: "start" | "end";
+  toolUseId: string;
+  toolName: string;
+  input?: Record<string, unknown>;
+  outputText?: string;
+  isError?: boolean;
+}
+
+export interface ChatStatusItem extends ChatItemBase {
+  kind: "status";
+  status: "yielded" | "error" | "system";
+  text: string;
+}
+
+export type ChatItem =
+  | ChatTextItem
+  | ChatMediaItem
+  | ChatToolItem
+  | ChatStatusItem;
+
+export interface ChatItemHistoryResult {
+  items: ChatItem[];
+  hasMore: boolean;
+  cursor: string;
+}