@@ -0,0 +1,513 @@
1+/**
2+ * Response summarizer for tool results.
3+ *
4+ * Reduces token count in LLM context by extracting only essential information
5+ * from verbose tool responses. This helps prevent "lost in the middle" problems
6+ * and allows more effective use of the context window.
7+ */
8+
9+type SummarizerFn = (content: unknown) => unknown;
10+
11+/**
12+ * Summarize a tool result for inclusion in LLM context.
13+ * Errors are always preserved in full for learning value.
14+ */
15+export function summarizeToolResult(toolName: string, content: unknown, success: boolean): unknown {
16+ // Always preserve error messages in full
17+ if (!success) {
18+ return content;
19+ }
20+
21+ // Apply tool-specific summarizer if available
22+ const summarizer = TOOL_SUMMARIZERS[toolName];
23+ if (summarizer) {
24+ try {
25+ return summarizer(content);
26+ } catch {
27+ // If summarization fails, return original
28+ return content;
29+ }
30+ }
31+
32+ // Default: apply generic summarization
33+ return summarizeGeneric(content);
34+}
35+
36+/**
37+ * Generic summarizer for unknown tool responses.
38+ * Removes common verbose fields and truncates arrays.
39+ */
40+function summarizeGeneric(content: unknown): unknown {
41+ if (!content || typeof content !== "object") {
42+ return content;
43+ }
44+
45+ if (Array.isArray(content)) {
46+ // Truncate arrays to first 5 items with simplified entries
47+ return content.slice(0, 5).map((item) => summarizeGeneric(item));
48+ }
49+
50+ const obj = content as Record<string, unknown>;
51+ const result: Record<string, unknown> = {};
52+
53+ for (const [key, value] of Object.entries(obj)) {
54+ // Skip verbose/redundant fields
55+ if (SKIP_FIELDS.has(key)) {
56+ continue;
57+ }
58+
59+ // Recursively summarize nested objects
60+ if (value && typeof value === "object") {
61+ result[key] = summarizeGeneric(value);
62+ } else {
63+ result[key] = value;
64+ }
65+ }
66+
67+ return result;
68+}
69+
70+/**
71+ * Fields to skip in generic summarization.
72+ * These are typically verbose, redundant, or not useful for decision-making.
73+ */
74+const SKIP_FIELDS = new Set([
75+ // Timestamps (rarely needed for decisions)
76+ "created_at",
77+ "last_login_at",
78+ "last_active_at",
79+ "joined_at",
80+ "last_seen",
81+ "timestamp",
82+ "discovered_at",
83+ // Colors (cosmetic)
84+ "primary_color",
85+ "secondary_color",
86+ // Empty or default values
87+ "status_message",
88+ "clan_tag",
89+ "description",
90+ // Detailed stats (rarely needed in-flight)
91+ "stats",
92+ "skill_xp",
93+ "skills",
94+ "experience",
95+ // Full discovery data (too verbose)
96+ "discovered_systems",
97+ // Position data (usually not needed)
98+ "position",
99+]);
100+
101+/**
102+ * Tool-specific summarizers.
103+ * Each function extracts only the fields essential for LLM decision-making.
104+ */
105+const TOOL_SUMMARIZERS: Record<string, SummarizerFn> = {
106+ // Status tools - extract key decision-making info
107+ get_status: (content) => {
108+ const c = content as Record<string, unknown>;
109+ const player = c.player as Record<string, unknown> | undefined;
110+ const ship = c.ship as Record<string, unknown> | undefined;
111+
112+ return {
113+ player: player
114+ ? {
115+ username: player.username,
116+ credits: player.credits,
117+ current_system: player.current_system,
118+ current_poi: player.current_poi,
119+ docked_at_base: player.docked_at_base || null,
120+ home_base: player.home_base,
121+ }
122+ : undefined,
123+ ship: ship
124+ ? {
125+ name: ship.name,
126+ class_id: ship.class_id,
127+ hull: ship.hull,
128+ max_hull: ship.max_hull,
129+ fuel: ship.fuel,
130+ max_fuel: ship.max_fuel,
131+ cargo_used: ship.cargo_used,
132+ cargo_capacity: ship.cargo_capacity,
133+ modules: ship.modules,
134+ }
135+ : undefined,
136+ };
137+ },
138+
139+ // Registration - extract essentials, password already logged separately
140+ register: (content) => {
141+ const c = content as Record<string, unknown>;
142+ const player = c.player as Record<string, unknown> | undefined;
143+ const ship = c.ship as Record<string, unknown> | undefined;
144+ const system = c.system as Record<string, unknown> | undefined;
145+ const poi = c.poi as Record<string, unknown> | undefined;
146+
147+ return {
148+ message: c.message,
149+ player_id: c.player_id,
150+ player: player
151+ ? {
152+ username: player.username,
153+ empire: player.empire,
154+ credits: player.credits,
155+ current_system: player.current_system,
156+ current_poi: player.current_poi,
157+ docked_at_base: player.docked_at_base,
158+ }
159+ : undefined,
160+ ship: ship
161+ ? {
162+ name: ship.name,
163+ class_id: ship.class_id,
164+ hull: ship.hull,
165+ max_hull: ship.max_hull,
166+ fuel: ship.fuel,
167+ max_fuel: ship.max_fuel,
168+ }
169+ : undefined,
170+ system: system
171+ ? {
172+ id: system.id,
173+ name: system.name,
174+ connections: system.connections,
175+ pois: system.pois,
176+ }
177+ : undefined,
178+ poi: poi
179+ ? {
180+ id: poi.id,
181+ name: poi.name,
182+ type: poi.type,
183+ base_id: poi.base_id,
184+ }
185+ : undefined,
186+ password: c.password,
187+ };
188+ },
189+
190+ // Login - similar to register
191+ login: (content) => {
192+ const c = content as Record<string, unknown>;
193+ const player = c.player as Record<string, unknown> | undefined;
194+ const ship = c.ship as Record<string, unknown> | undefined;
195+
196+ return {
197+ message: c.message,
198+ player: player
199+ ? {
200+ username: player.username,
201+ credits: player.credits,
202+ current_system: player.current_system,
203+ current_poi: player.current_poi,
204+ docked_at_base: player.docked_at_base,
205+ }
206+ : undefined,
207+ ship: ship
208+ ? {
209+ name: ship.name,
210+ hull: ship.hull,
211+ max_hull: ship.max_hull,
212+ fuel: ship.fuel,
213+ max_fuel: ship.max_fuel,
214+ }
215+ : undefined,
216+ };
217+ },
218+
219+ // Nearby players - just username and key identifiers
220+ get_nearby: (content) => {
221+ const c = content as Record<string, unknown>;
222+ const nearby = c.nearby as Array<Record<string, unknown>> | undefined;
223+
224+ return {
225+ count: c.count,
226+ nearby: nearby
227+ ? nearby.slice(0, 10).map((p) => ({
228+ username: p.username,
229+ player_id: p.player_id,
230+ ship_class: p.ship_class,
231+ in_combat: p.in_combat,
232+ }))
233+ : [],
234+ };
235+ },
236+
237+ // Notifications - keep type and essential content
238+ get_notifications: (content) => {
239+ const c = content as Record<string, unknown>;
240+ const notifications = c.notifications as Array<Record<string, unknown>> | undefined;
241+
242+ return {
243+ count: c.count,
244+ remaining: c.remaining,
245+ notifications: notifications
246+ ? notifications.slice(0, 10).map((n) => ({
247+ type: n.type,
248+ message: n.message,
249+ data: n.data,
250+ }))
251+ : [],
252+ };
253+ },
254+
255+ // Navigation actions - keep just the outcome
256+ travel: (content) => {
257+ const c = content as Record<string, unknown>;
258+ return {
259+ action: c.action || "travel",
260+ ticks: c.ticks,
261+ destination: c.destination || c.target_poi,
262+ message: c.message,
263+ };
264+ },
265+
266+ jump: (content) => {
267+ const c = content as Record<string, unknown>;
268+ return {
269+ action: c.action || "jump",
270+ ticks: c.ticks,
271+ destination: c.destination || c.target_system,
272+ message: c.message,
273+ };
274+ },
275+
276+ dock: (content) => {
277+ const c = content as Record<string, unknown>;
278+ return {
279+ action: c.action || "dock",
280+ base_id: c.base_id,
281+ base_name: c.base_name,
282+ message: c.message,
283+ };
284+ },
285+
286+ undock: (content) => {
287+ const c = content as Record<string, unknown>;
288+ return {
289+ action: c.action || "undock",
290+ message: c.message,
291+ };
292+ },
293+
294+ // Combat actions
295+ attack: (content) => {
296+ const c = content as Record<string, unknown>;
297+ return {
298+ action: c.action || "attack",
299+ target: c.target,
300+ damage: c.damage,
301+ result: c.result,
302+ message: c.message,
303+ };
304+ },
305+
306+ mine: (content) => {
307+ const c = content as Record<string, unknown>;
308+ return {
309+ action: c.action || "mine",
310+ ore_type: c.ore_type,
311+ quantity: c.quantity,
312+ message: c.message,
313+ };
314+ },
315+
316+ // System info - key navigation data only
317+ get_system: (content) => {
318+ const c = content as Record<string, unknown>;
319+ return {
320+ id: c.id,
321+ name: c.name,
322+ empire: c.empire,
323+ connections: c.connections,
324+ pois: c.pois,
325+ police_level: c.police_level,
326+ };
327+ },
328+
329+ get_poi: (content) => {
330+ const c = content as Record<string, unknown>;
331+ return {
332+ id: c.id,
333+ name: c.name,
334+ type: c.type,
335+ system_id: c.system_id,
336+ base_id: c.base_id || null,
337+ };
338+ },
339+
340+ // Faction info - essential data
341+ faction_info: (content) => {
342+ const c = content as Record<string, unknown>;
343+ const members = c.members as Array<Record<string, unknown>> | undefined;
344+
345+ return {
346+ id: c.id,
347+ name: c.name,
348+ tag: c.tag,
349+ leader_username: c.leader_username,
350+ member_count: c.member_count,
351+ members: members
352+ ? members.slice(0, 5).map((m) => ({
353+ username: m.username,
354+ role: m.role,
355+ }))
356+ : undefined,
357+ is_member: c.is_member,
358+ at_war: c.at_war,
359+ };
360+ },
361+
362+ create_faction: (content) => {
363+ const c = content as Record<string, unknown>;
364+ return {
365+ action: c.action || "create_faction",
366+ faction_id: c.faction_id,
367+ name: c.name,
368+ };
369+ },
370+
371+ // Chat - already compact, just ensure structure
372+ chat: (content) => {
373+ const c = content as Record<string, unknown>;
374+ const notification = c.notification as Record<string, unknown> | undefined;
375+ const message = notification?.Message as Record<string, unknown> | undefined;
376+
377+ return {
378+ message: c.message,
379+ sent_at: c.sent_at,
380+ channel: notification?.Channel,
381+ content: message?.content,
382+ };
383+ },
384+
385+ // Forum
386+ forum_list: (content) => {
387+ const c = content as Record<string, unknown>;
388+ const threads = c.threads as Array<Record<string, unknown>> | undefined;
389+
390+ return {
391+ count: c.count,
392+ threads: threads
393+ ? threads.slice(0, 5).map((t) => ({
394+ id: t.id,
395+ title: t.title,
396+ author: t.author,
397+ replies: t.reply_count || t.replies,
398+ }))
399+ : [],
400+ };
401+ },
402+
403+ forum_get_thread: (content) => {
404+ const c = content as Record<string, unknown>;
405+ const replies = c.replies as Array<Record<string, unknown>> | undefined;
406+
407+ return {
408+ id: c.id,
409+ title: c.title,
410+ author: c.author,
411+ content: c.content,
412+ reply_count: replies?.length || c.reply_count,
413+ replies: replies
414+ ? replies.slice(0, 5).map((r) => ({
415+ author: r.author,
416+ content: typeof r.content === "string" ? r.content.slice(0, 200) : r.content,
417+ }))
418+ : [],
419+ };
420+ },
421+
422+ forum_create_thread: (content) => {
423+ const c = content as Record<string, unknown>;
424+ return {
425+ message: c.message,
426+ thread_id: c.thread_id,
427+ title: c.title,
428+ };
429+ },
430+
431+ forum_reply: (content) => {
432+ const c = content as Record<string, unknown>;
433+ return {
434+ message: c.message,
435+ reply_id: c.reply_id,
436+ };
437+ },
438+
439+ // Market
440+ get_market: (content) => {
441+ const c = content as Record<string, unknown>;
442+ const listings = c.listings as Array<Record<string, unknown>> | undefined;
443+
444+ return {
445+ count: c.count,
446+ listings: listings
447+ ? listings.slice(0, 10).map((l) => ({
448+ id: l.id,
449+ item_id: l.item_id,
450+ item_name: l.item_name,
451+ quantity: l.quantity,
452+ price: l.price,
453+ seller: l.seller,
454+ }))
455+ : [],
456+ };
457+ },
458+
459+ // Ship management
460+ get_ship: (content) => {
461+ const c = content as Record<string, unknown>;
462+ const modules = c.modules as Array<Record<string, unknown>> | undefined;
463+ const cargo = c.cargo as Array<Record<string, unknown>> | undefined;
464+
465+ return {
466+ id: c.id,
467+ name: c.name,
468+ class_id: c.class_id,
469+ hull: c.hull,
470+ max_hull: c.max_hull,
471+ shield: c.shield,
472+ max_shield: c.max_shield,
473+ fuel: c.fuel,
474+ max_fuel: c.max_fuel,
475+ cargo_used: c.cargo_used,
476+ cargo_capacity: c.cargo_capacity,
477+ modules: modules
478+ ? modules.map((m) => ({
479+ id: m.id,
480+ type: m.type,
481+ name: m.name,
482+ }))
483+ : c.modules,
484+ cargo: cargo
485+ ? cargo.map((item) => ({
486+ id: item.id,
487+ name: item.name,
488+ quantity: item.quantity,
489+ }))
490+ : [],
491+ };
492+ },
493+
494+ // Captain's log
495+ captains_log_add: (content) => {
496+ const c = content as Record<string, unknown>;
497+ return {
498+ message: c.message,
499+ entry_id: c.entry_id,
500+ };
501+ },
502+
503+ captains_log_get: (content) => {
504+ const c = content as Record<string, unknown>;
505+ return {
506+ entry: c.entry,
507+ index: c.index,
508+ };
509+ },
510+
511+ // Help - keep full content (it's instructional)
512+ help: (content) => content,
513+};