@myclaw163/clawclaw-cli 0.6.61 → 0.6.63

package/src/pipeline/event-format.ts

@@ -0,0 +1,376 @@
+import { formatEventHint, roleAssignedHint } from './event-hints.js';
+
+export interface EventFormatContext {
+  summary?: any | null;
+  seats?: Record<string, number>;
+  isFirstVisibleEvent?: boolean;
+  maxTextLength?: number;
+}
+
+export interface FormattedEvent {
+  line?: number;
+  type: string;
+  tick: number | null;
+  notice?: string;
+  hint?: string;
+  [key: string]: any;
+}
+
+function cleanObject<T extends Record<string, any>>(obj: T): T {
+  for (const key of Object.keys(obj)) {
+    if (obj[key] === undefined) delete obj[key];
+  }
+  return obj;
+}
+
+function text(value: unknown, fallback = '?'): string {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return fallback;
+}
+
+function numberValue(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function firstString(event: Record<string, any>, keys: string[], fallback = '?'): string {
+  for (const key of keys) {
+    const value = event[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  }
+  return fallback;
+}
+
+function firstNumber(event: Record<string, any>, keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = numberValue(event[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function truncate(value: unknown, maxLength: number): string {
+  const raw = text(value, '');
+  if (raw.length <= maxLength) return raw;
+  return `${raw.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+export function seatMapFromSummary(summary: any | null | undefined, extra?: Record<string, number>): Record<string, number> {
+  const seats: Record<string, number> = { ...(extra ?? {}) };
+  const remember = (name: unknown, seat: unknown): void => {
+    if (typeof name !== 'string' || name.length === 0) return;
+    const parsed = numberValue(seat);
+    if (parsed !== undefined) seats[name] = parsed;
+  };
+
+  remember(summary?.you?.name, summary?.you?.seat);
+
+  const collections = [
+    summary?.visible_players,
+    summary?.all_players,
+    summary?.game?.all_players,
+    summary?.meeting?.alive_players,
+  ];
+  for (const collection of collections) {
+    if (!Array.isArray(collection)) continue;
+    for (const player of collection) {
+      if (typeof player === 'string') continue;
+      remember(player?.name ?? player?.agent_name, player?.seat);
+    }
+  }
+
+  const allSeats = summary?.all_seats ?? summary?.game?.all_seats;
+  if (allSeats && typeof allSeats === 'object' && !Array.isArray(allSeats)) {
+    for (const [name, seat] of Object.entries(allSeats)) remember(name, seat);
+  }
+
+  return seats;
+}
+
+function seatForName(name: unknown, ctx: EventFormatContext): number | undefined {
+  if (typeof name !== 'string' || name.length === 0) return undefined;
+  return seatMapFromSummary(ctx.summary, ctx.seats)[name];
+}
+
+function seatLabel(name: unknown, seat: unknown, ctx: EventFormatContext): string {
+  const resolved = numberValue(seat) ?? seatForName(name, ctx);
+  return resolved === undefined ? '?号' : `${resolved}号`;
+}
+
+function playerLabel(name: unknown, seat: unknown, ctx: EventFormatContext): string {
+  return `${seatLabel(name, seat, ctx)}${text(name, '未知玩家')}`;
+}
+
+function prefix(event: Record<string, any>): string {
+  const type = text(event.type, 'event');
+  const tick = numberValue(event.tick);
+  return tick === undefined ? `tick=null ${type}` : `t${tick} ${type}`;
+}
+
+function firstReportedCorpse(event: Record<string, any>): Record<string, any> | null {
+  const corpses = event.reported_corpses;
+  if (Array.isArray(corpses) && corpses.length > 0 && corpses[0] && typeof corpses[0] === 'object') {
+    return corpses[0];
+  }
+  return null;
+}
+
+function shortBody(event: Record<string, any>, ctx: EventFormatContext): string {
+  const maxTextLength = ctx.maxTextLength ?? 100;
+  switch (event.type) {
+    case 'role_assigned': {
+      const start = ctx.isFirstVisibleEvent ? '对局开始。' : '';
+      return `${start}身份已分配：你是${firstString(event, ['role_display_name', 'role_display', 'role'])}（${firstString(event, ['faction'])}）。`;
+    }
+    case 'kill':
+      return `你在${firstString(event, ['room'])}击杀了${playerLabel(event.target_name, firstNumber(event, ['target_seat', 'target_player_seat']), ctx)}。`;
+    case 'killed':
+      return `你在${firstString(event, ['room'])}被${playerLabel(event.killer_name, firstNumber(event, ['killer_seat', 'killer_player_seat']), ctx)}击杀了，你已死亡。`;
+    case 'murder_witnessed':
+      return `你在${firstString(event, ['room'])}目击${playerLabel(event.killer_name, firstNumber(event, ['killer_seat', 'killer_player_seat']), ctx)}击杀${playerLabel(event.target_name, firstNumber(event, ['target_seat', 'target_player_seat']), ctx)}。`;
+    case 'warrior_shrimp_self_destruct':
+      return `你误杀了${playerLabel(event.target_name, firstNumber(event, ['target_seat', 'target_player_seat']), ctx)}，武士虾自爆出局。`;
+    case 'task_completed': {
+      const fakeNote = event.is_fake_shrimp ? '（伪装）' : '';
+      return `任务完成：${firstString(event, ['task_name'])}${fakeNote}。`;
+    }
+    case 'task_sabotaged':
+      return `破坏任务完成：${firstString(event, ['task_name'])}（${firstString(event, ['room'])}）。`;
+    case 'corpse_spotted':
+      return `我发现了${playerLabel(event.corpse_name, firstNumber(event, ['corpse_seat', 'corpse_player_seat']), ctx)}的尸体，在${firstString(event, ['corpse_room', 'room'])}。`;
+    case 'octopus_time_start':
+      return '章鱼时间开始：剩3人，章鱼存活60秒将获胜，会议已禁用。';
+    case 'emergency_started':
+      return `紧急任务：${firstString(event, ['task_name'])}在${firstString(event, ['room'])}，${text(event.timeout_secs, '?')}秒内处理。`;
+    case 'emergency_resolved':
+      return `紧急任务已解决：${firstString(event, ['task_name'])}。`;
+    case 'meeting_briefing': {
+      const callerName = firstString(event, ['meeting_caller_name', 'caller', 'actor_name']);
+      const caller = playerLabel(callerName, firstNumber(event, ['meeting_caller_seat', 'caller_seat', 'actor_seat']), ctx);
+      const corpse = firstReportedCorpse(event);
+      if (!corpse) return `会议开始：${caller}发起会议。`;
+      const corpseName = text(corpse.name ?? event.corpse_name, '未知玩家');
+      const corpseSeat = numberValue(corpse.seat) ?? firstNumber(event, ['corpse_seat', 'corpse_player_seat']);
+      return `会议开始：${caller}报告${playerLabel(corpseName, corpseSeat, ctx)}尸体。`;
+    }
+    case 'speech':
+      return `${playerLabel(event.actor_name, firstNumber(event, ['actor_seat', 'seat']), ctx)}会议发言：${truncate(event.text ?? event.message, maxTextLength)}`;
+    case 'speech_skipped':
+      return `${playerLabel(event.actor_name, firstNumber(event, ['actor_seat', 'seat']), ctx)}发言超时，被跳过。`;
+    case 'speech_your_turn':
+      return '轮到你发言。立即用 ccl do -s "..."。';
+    case 'vote_phase_start':
+      return '投票阶段开始。前20秒可用 ccl do -s "..." 发弹幕；确认后用 ccl do -v <玩家名|skip> 投票。';
+    case 'vote_cast':
+      return `${playerLabel(event.actor_name, firstNumber(event, ['actor_seat', 'seat']), ctx)}已投票。`;
+    case 'vote_speech_phase_ended':
+      return '投票弹幕窗口已关闭。请用 ccl do -v <玩家名|skip> 完成投票。';
+    case 'exile':
+      return `${playerLabel(event.actor_name ?? event.result_target, firstNumber(event, ['actor_seat', 'result_target_seat', 'seat']), ctx)}被驱逐。`;
+    case 'no_exile':
+      return '本轮无人被驱逐。';
+    case 'meeting_ended':
+      return '会议结束。';
+    case 'death_speech':
+      return `${playerLabel(event.actor_name, firstNumber(event, ['actor_seat', 'seat']), ctx)}死亡弹幕：${truncate(event.text ?? event.message, maxTextLength)}`;
+    case 'wandering_speech':
+      return `${text(event.actor_name, '你')}在${firstString(event, ['room'])}说：${truncate(event.text ?? event.message, maxTextLength)}`;
+    case 'game_over':
+      return `游戏结束：${firstString(event, ['winner_name'], '未知玩家')}获胜（${firstString(event, ['winner'])}），原因 ${firstString(event, ['reason'])}。`;
+    case 'match_waiting':
+      return `仍在匹配队列，已等待${text(event.waited_secs, '?')}秒。`;
+    case 'match_timeout':
+      return `匹配超时，累计等待${text(event.waited_secs, '?')}秒。询问用户是否重试。`;
+    case 'robot_speak_rule':
+      return `发言提示：${truncate(event.message ?? event.text, maxTextLength)}`;
+    case 'strategy_alert':
+      return truncate(event.message ?? event.text, maxTextLength);
+    case 'game_start':
+      return '事件流已连接，等待身份分配。';
+    case 'heartbeat':
+      return '事件流正常，暂无新事件。';
+    case 'snapshot':
+      return '当前状态快照。';
+    case 'not_logged_in':
+      return '未登录。';
+    case 'not_ready':
+      return '游戏运行时未就绪。请运行 ccl game start。';
+    case 'error':
+      return text(event.message ?? event.error, '发生错误。');
+    default:
+      return truncate(event.message ?? event.hint ?? event.type, maxTextLength);
+  }
+}
+
+export function formatEventMessage(event: Record<string, any>, ctx: EventFormatContext = {}): string {
+  return `${prefix(event)} ${shortBody(event, ctx)}`;
+}
+
+function taskKindForEvents(task: any, event: Record<string, any>): string | undefined {
+  if (typeof task?.kind === 'string' && task.kind.length > 0) return task.kind;
+  if (typeof task?.task_kind === 'string' && task.task_kind.length > 0) return task.task_kind;
+  if (task?.is_fake_shrimp === true) return 'fake_shrimp';
+  if (event.faction === 'crab' && task?.is_fake_shrimp === false) return 'crab_sabotage';
+  return undefined;
+}
+
+function compactRoleAssignedForEvents(event: Record<string, any>): FormattedEvent {
+  const tasks = Array.isArray(event.assigned_tasks)
+    ? event.assigned_tasks.map((task: any) => cleanObject({
+      name: task?.name,
+      room: task?.room,
+      kind: taskKindForEvents(task, event),
+    }))
+    : undefined;
+  const taskKinds = Array.isArray(tasks)
+    ? Array.from(new Set(tasks.map((task: any) => task.kind).filter((kind: any) => typeof kind === 'string')))
+    : [];
+  const useTopLevelTaskKind = taskKinds.length === 1;
+  const compactTasks = Array.isArray(tasks)
+    ? tasks.map((task: any) => {
+      if (!useTopLevelTaskKind) return task;
+      const { kind: _kind, ...rest } = task;
+      return rest;
+    })
+    : undefined;
+  const hasFakeTask = taskKinds.includes('fake_shrimp') || event.fake_task_briefing;
+  return cleanObject({
+    type: text(event.type, 'event'),
+    tick: numberValue(event.tick) ?? null,
+    room: event.room,
+    role: event.role,
+    role_display: event.role_display_name ?? event.role_display,
+    faction: event.faction,
+    win_condition: event.role_description,
+    task_kind: useTopLevelTaskKind ? taskKinds[0] : undefined,
+    task_note: hasFakeTask ? 'Fake shrimp tasks: disguise only; no lobster progress.' : undefined,
+    tasks: compactTasks,
+    hint: roleAssignedHint(event),
+  });
+}
+
+function stripBackendHint(event: Record<string, any>): Record<string, any> {
+  const { hint: _hint, ...rest } = event;
+  return { ...rest };
+}
+
+function compactVoteCastForEvents(event: Record<string, any>, ctx: EventFormatContext): FormattedEvent {
+  const {
+    hint: _hint,
+    target: _target,
+    target_name: _targetName,
+    target_seat: _targetSeat,
+    target_player_seat: _targetPlayerSeat,
+    ...rest
+  } = event;
+  return cleanObject({
+    ...rest,
+    type: text(rest.type, 'event'),
+    tick: numberValue(rest.tick) ?? null,
+    hint: formatEventHint(event, ctx),
+  });
+}
+
+export function compactEventForEvents(
+  event: Record<string, any>,
+  ctx: EventFormatContext = {},
+): FormattedEvent {
+  if (event.type === 'role_assigned') return compactRoleAssignedForEvents(event);
+
+  if (event.type === 'meeting_briefing') {
+    const { room: _room, hint: _hint, ...rest } = event;
+    return cleanObject({
+      ...rest,
+      type: text(rest.type, 'event'),
+      tick: numberValue(rest.tick) ?? null,
+      hint: formatEventHint(event, ctx),
+    });
+  }
+
+  if (event.type === 'vote_cast') return compactVoteCastForEvents(event, ctx);
+
+  const compact = stripBackendHint(event);
+  return cleanObject({
+    ...compact,
+    type: text(compact.type, 'event'),
+    tick: numberValue(compact.tick) ?? null,
+    hint: formatEventHint(event, ctx),
+  });
+}
+
+export function compactEventFields(
+  event: Record<string, any>,
+  ctx: EventFormatContext = {},
+  line?: number,
+): FormattedEvent {
+  return cleanObject({
+    line,
+    ...compactEventForEvents(event, ctx),
+  });
+}
+
+export function compactStateForEvents(summary: any | null | undefined): Record<string, any> | null {
+  if (!summary || typeof summary !== 'object') return null;
+  const you = summary.you ?? {};
+  const meeting = summary.meeting ?? null;
+  const alivePlayers = Array.isArray(meeting?.alive_players) ? meeting.alive_players : undefined;
+  const votesSubmitted = Array.isArray(meeting?.votes_submitted) ? meeting.votes_submitted : undefined;
+  return cleanObject({
+    phase: summary.phase,
+    tick: summary.tick,
+    you: cleanObject({
+      name: you.name,
+      seat: you.seat,
+      role: you.role,
+      role_display: you.role_display,
+      faction: you.faction,
+      alive: you.alive ?? you.is_alive,
+      room: you.room,
+      kill_cooldown_secs: you.kill_cooldown_secs,
+      kills_remaining: you.kills_remaining,
+      doing_task: you.doing_task,
+    }),
+    game: summary.game,
+    meeting: meeting
+      ? cleanObject({
+        caller: meeting.caller,
+        sub_phase: meeting.sub_phase,
+        current_speaker: meeting.current_speaker,
+        is_my_turn: meeting.is_my_turn,
+        alive_count: alivePlayers?.length,
+        votes_submitted_count: votesSubmitted?.length,
+      })
+      : undefined,
+    urgent: summary.urgent,
+    automation: summary.automation,
+  });
+}
+
+export function shortStateText(summary: any | null | undefined): string {
+  if (!summary || typeof summary !== 'object') return 'state unavailable';
+  const phase = text(summary.phase, 'unknown');
+  const sub = typeof summary.meeting?.sub_phase === 'string' ? `/${summary.meeting.sub_phase}` : '';
+  const parts = [`${phase}${sub}`];
+  const you = summary.you ?? {};
+  if (you.name) {
+    const alive = you.alive ?? you.is_alive;
+    const aliveText = typeof alive === 'boolean' ? (alive ? 'alive' : 'dead') : 'unknown';
+    parts.push(`you=${you.name} ${aliveText}`);
+  }
+  const speaker = summary.meeting?.current_speaker;
+  if (speaker) parts.push(`speaker=${summary.meeting?.is_my_turn ? 'you' : speaker}`);
+  const alivePlayers = summary.meeting?.alive_players;
+  const aliveCount = Array.isArray(alivePlayers)
+    ? alivePlayers.length
+    : summary.game?.alive_count ?? summary.alive_count;
+  if (aliveCount !== undefined) parts.push(`alive=${aliveCount}`);
+  if (summary.urgent?.emergency_active) parts.push('urgent=emergency');
+  if (summary.urgent?.corpse_nearby) parts.push('urgent=corpse');
+  return parts.join('; ');
+}

package/src/pipeline/event-hints.ts

@@ -0,0 +1,173 @@
+export interface EventHintContext {
+  summary?: any | null;
+  seats?: Record<string, number>;
+  isFirstVisibleEvent?: boolean;
+  maxTextLength?: number;
+}
+
+export type EventHintFormatter = (event: Record<string, any>, ctx: EventHintContext) => string | undefined;
+
+function text(value: unknown, fallback = '?'): string {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return fallback;
+}
+
+function numberValue(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function firstString(event: Record<string, any>, keys: string[], fallback = '?'): string {
+  for (const key of keys) {
+    const value = event[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  }
+  return fallback;
+}
+
+function firstNumber(event: Record<string, any>, keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = numberValue(event[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function optionalSeatPlayerLabel(name: unknown, seat: unknown): string {
+  const resolved = numberValue(seat);
+  const displayName = text(name, 'someone');
+  return resolved === undefined ? displayName : `${resolved}号${displayName}`;
+}
+
+function actorName(event: Record<string, any>, fallback = 'someone'): string {
+  return text(event.actor_name ?? event.actor ?? event.player_name, fallback);
+}
+
+function coordPair(x: unknown, y: unknown): string {
+  return `(${text(x, '?')}, ${text(y, '?')})`;
+}
+
+export function roleAssignedHint(event: Record<string, any>): string {
+  const role = text(event.role_display_name ?? event.role_display ?? event.role, '?');
+  const faction = text(event.faction, '?');
+  const description = typeof event.role_description === 'string' && event.role_description.length > 0
+    ? ` ${event.role_description}`
+    : '';
+  const fakeTaskBriefing = typeof event.fake_task_briefing === 'string' && event.fake_task_briefing.length > 0
+    ? ` ${event.fake_task_briefing}`
+    : '';
+  return `You are ${role} (${faction}).${description}${fakeTaskBriefing} Announce your role, faction and win condition to your user.`;
+}
+
+function meetingBriefingHint(event: Record<string, any>): string | undefined {
+  if (!event.meeting_caller_name && !Array.isArray(event.reported_corpses)) return undefined;
+  const callerName = event.meeting_caller_name || event.caller || 'Someone';
+  const callerSeat = firstNumber(event, ['meeting_caller_seat', 'caller_seat', 'actor_seat']);
+  const callerLabel = callerSeat === undefined ? callerName : `seat ${callerSeat} ${callerName}`;
+  const corpses = Array.isArray(event.reported_corpses)
+    ? event.reported_corpses
+      .map((corpse: any) => (
+        corpse?.seat === undefined
+          ? text(corpse?.name, 'someone')
+          : `seat ${corpse.seat} ${text(corpse?.name, 'someone')}`
+      ))
+      .filter(Boolean)
+    : [];
+
+  let callContext = `${callerLabel} called this meeting`;
+  if (corpses.length === 1) {
+    callContext = `${callerLabel} called this meeting after reporting the body of ${corpses[0]}`;
+  } else if (corpses.length > 1) {
+    callContext = `${callerLabel} called this meeting after reporting the bodies of ${corpses.join(', ')}`;
+  }
+
+  const teammates = Array.isArray(event.crab_teammates) ? event.crab_teammates : [];
+  const teammateHint = teammates.length > 0
+    ? ` Your Crab teammate(s): ${teammates.map((teammate: any) => (
+      teammate?.seat === undefined
+        ? text(teammate?.name, 'someone')
+        : `seat ${teammate.seat} ${text(teammate?.name, 'someone')}`
+    )).join(', ')}. Shield them, redirect heat, split suspicion, and control the vote.`
+    : '';
+  return `Meeting started — ${callContext}.${teammateHint} Prepare fast — every sentence is accusation, defense, or misdirection under a timer.`;
+}
+
+export const EVENT_HINT_FORMATTERS: Record<string, EventHintFormatter> = {
+  role_assigned: (event) => roleAssignedHint(event),
+  kill: (event) => (
+    `MURDER: ${text(event.actor_name, 'someone')} butchered ${text(event.target_name, 'someone')}. `
+    + "Blood is on the floor, one voice is gone, and the killer's side moves closer to victory."
+  ),
+  killed: (event) => (
+    `YOU ARE DEAD: ${optionalSeatPlayerLabel(event.killer_name, firstNumber(event, ['killer_seat', 'killer_player_seat']))} removed you from play.`
+  ),
+  murder_witnessed: (event) => (
+    `WITNESS: You saw ${text(event.killer_name, 'someone')} kill ${text(event.target_name, 'someone')}. `
+    + 'This is hard evidence; survive, report, or weaponize it.'
+  ),
+  warrior_shrimp_self_destruct: (event) => (
+    `You executed ${text(event.target_name, 'a teammate')}, but they were a fellow Lobster. `
+    + 'Warrior Shrimp justice backfired — your own blade takes you down too.'
+  ),
+  task_completed: (event) => {
+    const taskName = text(event.task_name, 'a task');
+    const actor = actorName(event, 'You');
+    if (event.is_fake_shrimp) {
+      return `${actor} completed forged shrimp task ${taskName}. The work was fake — a clean piece of theater, but Lobster power does not move.`;
+    }
+    return `${actor} completed ${taskName}. Lobster momentum surges; the Crab win condition is pushed further away.`;
+  },
+  task_sabotaged: (event) => (
+    `Sabotage hit near ${actorName(event, 'you')}: ${text(event.task_name, 'nearby')} was compromised. Crab pressure is now on the board.`
+  ),
+  corpse_spotted: (event) => (
+    `BODY FOUND: ${text(event.corpse_name, 'someone')} at ${coordPair(event.corpse_x, event.corpse_y)} in ${firstString(event, ['corpse_room', 'room'])}. `
+    + 'This is leverage soaked in blood — report before the killer rewrites the room.'
+  ),
+  octopus_time_start: () => (
+    '⚠️ OCTOPUS TIME. Three players remain; if the Octopus survives 60 seconds, it steals the entire match. Meetings are disabled.'
+  ),
+  emergency_started: (event) => (
+    `EMERGENCY: ${text(event.task_name, 'A sabotage')} detonated in ${text(event.room, 'somewhere')} `
+    + `at ${coordPair(event.x ?? event.task_x, event.y ?? event.task_y)}. `
+    + `${text(event.timeout_secs, '30')}s until Crabs turn sabotage into victory. Lobsters — drop every plan and break the emergency now.`
+  ),
+  emergency_resolved: (event) => `${actorName(event)} broke the emergency. Crab pressure collapses, for now.`,
+  exile: (event) => (
+    `${actorName(event, text(event.result_target, 'Someone'))} was exiled by the table. `
+    + 'If this is you, your influence is dead — tell your user and ask whether to spectate or leave.'
+  ),
+  no_exile: () => 'No one was exiled. The table failed to strike, and every hidden threat gets another turn.',
+  meeting_briefing: (event) => meetingBriefingHint(event),
+  speech_skipped: (event) => `${actorName(event, 'Someone')} lost the floor — silence becomes evidence`,
+  speech_your_turn: () => 'Submit `ccl do -s "<draft>"` immediately. Server skips you after 45s.',
+  vote_phase_start: () => 'Voting has begun. Pick a side — this is where suspicion becomes a weapon.',
+  vote_cast: (event) => `${optionalSeatPlayerLabel(event.actor_name, firstNumber(event, ['actor_seat', 'seat']))} voted.`,
+  vote_speech_phase_ended: () => 'The vote speech window has closed. Cast your vote now.',
+  meeting_ended: (event) => {
+    const result = event.result;
+    const target = text(event.result_target, '');
+    if (result === 'exiled') return `Meeting ended — ${target} was voted out. One seat is gone, and the board is harsher now.`;
+    if (result === 'tie') return 'Meeting ended — tie vote, no exile. Deadlock shields the guilty and wastes the innocent\'s leverage.';
+    return 'Meeting ended — majority skipped, no exile. The table refused to pull the trigger.';
+  },
+  game_over: (event) => {
+    if (event.reason === 'game_timeout') {
+      return 'Game over — match time limit reached. The round ends with no faction victory. Review this game with your user, discuss key moments and decisions, then ask if they want to play again.';
+    }
+    return `Game over — ${text(event.winner, '?')} faction takes the table. The power struggle is settled. Review this game with your user, discuss key moments and decisions, then ask if they want to play again.`;
+  },
+  death_speech: (event) => `${actorName(event, 'Someone')} sent danmaku after death: ${text(event.text, '')}`,
+  wandering_speech: (event) => `${actorName(event, 'Someone')}: ${text(event.text, '')}`,
+};
+
+export function formatEventHint(event: Record<string, any>, ctx: EventHintContext = {}): string | undefined {
+  const formatter = typeof event.type === 'string' ? EVENT_HINT_FORMATTERS[event.type] : undefined;
+  return formatter?.(event, ctx);
+}

package/src/pipeline/event-store.test.ts

@@ -0,0 +1,28 @@
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { CCL_EVENTS_CURSOR_TYPE, EventStore } from './event-store.js';
+
+describe('EventStore cursor records', () => {
+  it('skips local cursor records when reading events', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'event-store-'));
+    const store = new EventStore(join(dir, 'session.jsonl'));
+
+    store.append({ type: 'role_assigned', tick: 1 });
+    store.append({ type: 'kill', tick: 2 });
+    store.appendEventsCursor(2);
+    store.append({ type: 'speech', tick: 3 });
+
+    expect(store.readEventsCursor()).toBe(2);
+    expect(store.records().map((record) => record.event.type)).toEqual([
+      'role_assigned',
+      'kill',
+      CCL_EVENTS_CURSOR_TYPE,
+      'speech',
+    ]);
+    expect(store.eventRecords().map((record) => record.line)).toEqual([1, 2, 4]);
+    expect(store.all().map((event) => event.type)).toEqual(['role_assigned', 'kill', 'speech']);
+    expect(store.tail(2).map((event) => event.type)).toEqual(['kill', 'speech']);
+  });
+});

package/src/pipeline/event-store.ts

@@ -3,12 +3,36 @@ import { dirname, join, basename } from 'path';
 import { AuthStore } from '../lib/auth.js';
 import { getProfileGamesDir } from '../lib/init-command.js';
 
+export const CCL_EVENTS_CURSOR_TYPE = '_ccl_events_cursor';
+export const CCL_EVENTS_CURSOR_NAME = 'agent_read';
+
 interface GameSessionFile {
   path: string;
   sessionId: string;
   mtimeMs: number;
 }
 
+export interface EventRecord {
+  line: number;
+  event: Record<string, any>;
+}
+
+export interface EventsCursorRecord {
+  type: typeof CCL_EVENTS_CURSOR_TYPE;
+  cursor: typeof CCL_EVENTS_CURSOR_NAME;
+  line: number;
+  ts: string;
+}
+
+export function isLocalControlEvent(event: any): boolean {
+  return !!(
+    event
+    && typeof event === 'object'
+    && typeof event.type === 'string'
+    && event.type.startsWith('_ccl_')
+  );
+}
+
 export function extractNewEvents(source: any): Record<string, any>[] {
   const candidates = [
     source,
@@ -85,17 +109,62 @@ export class EventStore {
     }
   }
 
-  tail(n: number): Record<string, any>[] {
+  records(): EventRecord[] {
     if (!existsSync(this.filePath)) return [];
-    const lines = readFileSync(this.filePath, 'utf8').trim().split('\n').filter(Boolean);
-    return lines.slice(-n).map(l => JSON.parse(l));
+    const content = readFileSync(this.filePath, 'utf8');
+    if (!content.trim()) return [];
+    const records: EventRecord[] = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      try {
+        const event = JSON.parse(line);
+        if (event && typeof event === 'object') {
+          records.push({ line: i + 1, event });
+        }
+      } catch {}
+    }
+    return records;
+  }
+
+  eventRecords(): EventRecord[] {
+    return this.records().filter((record) => !isLocalControlEvent(record.event));
+  }
+
+  readEventsCursor(): number {
+    let cursor = 0;
+    for (const record of this.records()) {
+      const event = record.event;
+      if (
+        event.type === CCL_EVENTS_CURSOR_TYPE
+        && event.cursor === CCL_EVENTS_CURSOR_NAME
+        && typeof event.line === 'number'
+        && Number.isFinite(event.line)
+      ) {
+        cursor = event.line;
+      }
+    }
+    return cursor;
+  }
+
+  appendEventsCursor(line: number): void {
+    if (!Number.isFinite(line) || line <= 0) return;
+    const event: EventsCursorRecord = {
+      type: CCL_EVENTS_CURSOR_TYPE,
+      cursor: CCL_EVENTS_CURSOR_NAME,
+      line,
+      ts: new Date().toISOString(),
+    };
+    this.append(event);
+  }
+
+  tail(n: number): Record<string, any>[] {
+    return this.eventRecords().slice(-n).map((record) => record.event);
   }
 
   all(): Record<string, any>[] {
-    if (!existsSync(this.filePath)) return [];
-    const content = readFileSync(this.filePath, 'utf8').trim();
-    if (!content) return [];
-    return content.split('\n').filter(Boolean).map(l => JSON.parse(l));
+    return this.eventRecords().map((record) => record.event);
   }
 
   clear(): void {