mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 19:40:34 +00:00
0050072b76
The four new photo link tools join the journal's tools: the journey chat offers them to editors, the trip chat loads them with the journey group and the home chat keeps none. A journeyPhotos card shows the photos as thumbnails with the entries they leave and reach, the first one marked as the cover in a new order, and a caption old to new; a library add shows the photos once they landed. A linked photo comes off again, an unlinked one goes back, moved photos go back and a caption is written back, each while nothing changed since. A new order of an entry's photos and a library add have no way back yet. The journal prompt names the photo tools.
466 lines
18 KiB
TypeScript
466 lines
18 KiB
TypeScript
import type { McpRegistryListing } from '../../nest-mcp';
|
|
import type { AiToolSpec } from '../ai-connections/ai-chat-client.interface';
|
|
import { PINNED_ARG } from './assistant-tools.constants';
|
|
import { PACKAGE_HELD_READS, PACKAGE_TOOL_CONTROLLERS } from './cards/registry';
|
|
|
|
/**
|
|
* Which of TREK's MCP tools the assistant is offered, and how. Every tool the
|
|
* registry holds is offered, except the few below that no approval makes
|
|
* safe; the scopes in ASSISTANT_SCOPES hide the rest of what must never run
|
|
* (deleting a trip, share and invite links, file contents, plugins). A tool
|
|
* annotated read-only runs at once, every other one waits as a change card.
|
|
*
|
|
* Offering all of them in every step would cost a lot of tokens and runs past
|
|
* what some providers take in one request, so a turn starts with the core of
|
|
* a trip (days, places, bookings, packing, to-dos, budget, weather, search)
|
|
* and the model loads an addon's tools when it needs them (USE_TOOLS_TOOL).
|
|
*/
|
|
|
|
/**
|
|
* The Studio book tools belong to the Studio's own chat, the journey scope
|
|
* (isOfferedInJourney below): a trip chat has no page to show a change on and
|
|
* an applied write would reload an open Studio from its cover. External MCP
|
|
* clients keep them; a trip conversation of the assistant never sees them.
|
|
*/
|
|
const STUDIO_ONLY_TOOLS: Readonly<Record<string, string>> = Object.fromEntries(
|
|
[
|
|
'get_book',
|
|
'describe_book_page',
|
|
'list_book_layouts',
|
|
'list_book_assets',
|
|
'create_book',
|
|
'add_book_pages',
|
|
'move_book_page',
|
|
'delete_book_pages',
|
|
'edit_book_page',
|
|
'set_book_cover',
|
|
'suggest_book_photos',
|
|
'set_book_setup',
|
|
'set_book_theme',
|
|
'duplicate_book_page',
|
|
'save_book_layout',
|
|
'remove_book_layout',
|
|
'design_book',
|
|
'get_book_design',
|
|
'revise_book_design',
|
|
'apply_book_design',
|
|
].map((name) => [name, 'a Studio book tool: offered in the Studio chat only, never in a trip chat']),
|
|
);
|
|
|
|
/** Never offered, whatever the user approves, each for the reason beside it. */
|
|
export const ASSISTANT_DENIED_TOOLS: Readonly<Record<string, string>> = {
|
|
delete_trip: 'irreversible, and it takes the conversation with it',
|
|
copy_trip: 'makes a trip outside the conversation',
|
|
create_trip: 'makes a trip outside the conversation',
|
|
leave_trip: 'changes who can see the trip',
|
|
add_trip_member: 'changes who can see the trip',
|
|
remove_trip_member: 'changes who can see the trip',
|
|
leave_collection: 'changes who can see the collection',
|
|
set_collection_member_role: 'changes who can see the collection',
|
|
remove_collection_member: 'changes who can see the collection',
|
|
add_journey_contributor: 'changes who can see the journey',
|
|
update_journey_contributor_role: 'changes who can see the journey',
|
|
remove_journey_contributor: 'changes who can see the journey',
|
|
invite_to_collection: 'invites a person; the model could pick whom',
|
|
send_vacay_invite: 'invites a person; the model could pick whom',
|
|
share_vacay_calendar: 'shares a calendar with a person',
|
|
create_share_link: 'mints a public link, whose token would reach the AI provider',
|
|
get_share_link: 'reads a public link token',
|
|
delete_share_link: 'belongs with the share links above',
|
|
get_trip_invite_link: 'reads an invite token',
|
|
create_trip_invite_link: 'mints an invite token',
|
|
delete_trip_invite_link: 'belongs with the invite links above',
|
|
get_journey_share_link: 'reads a public link token',
|
|
create_journey_share_link: 'mints a public link token',
|
|
delete_journey_share_link: 'belongs with the share links above',
|
|
get_trip_calendar_feed: 'reads a calendar feed token',
|
|
enable_trip_calendar_feed: 'mints a calendar feed token',
|
|
rotate_trip_calendar_feed: 'mints a calendar feed token',
|
|
disable_trip_calendar_feed: 'belongs with the feeds above',
|
|
get_all_trips_calendar_feed: 'reads a calendar feed token',
|
|
enable_all_trips_calendar_feed: 'mints a calendar feed token',
|
|
rotate_all_trips_calendar_feed: 'mints a calendar feed token',
|
|
disable_all_trips_calendar_feed: 'belongs with the feeds above',
|
|
import_places_from_url: 'fetches an address the model chooses',
|
|
read_trip_file: 'would send documents such as passports to the AI provider',
|
|
upload_trip_file: 'writes a file the model made up',
|
|
create_category: 'changes the categories of every user',
|
|
update_category: 'changes the categories of every user',
|
|
delete_category: 'changes the categories of every user',
|
|
create_manual_school_holiday_country: 'changes the holidays of every user',
|
|
create_manual_school_holiday_region: 'changes the holidays of every user',
|
|
update_manual_school_holiday_region: 'changes the holidays of every user',
|
|
delete_manual_school_holiday_region: 'changes the holidays of every user',
|
|
delete_manual_school_holiday_country: 'changes the holidays of every user',
|
|
...STUDIO_ONLY_TOOLS,
|
|
restore_book_page: 'an undo target only: it puts a book page back as an earlier change left it',
|
|
restore_book_layout: 'an undo target only: it puts back a layout an earlier change took away',
|
|
restore_book_revision: 'an undo target only: it puts the book back as an applied design found it',
|
|
};
|
|
|
|
/**
|
|
* Names that read like sharing but only list or take back what the user
|
|
* shared already. Any other name that shares, invites or publishes a feed
|
|
* must be denied above; the boot check holds the two apart.
|
|
*/
|
|
const SHARE_LIKE_SAFE: ReadonlySet<string> = new Set([
|
|
'set_packing_item_sharing',
|
|
'list_vacay_shares',
|
|
'get_shareable_vacay_users',
|
|
'get_shared_vacay_calendars',
|
|
'unshare_vacay_calendar',
|
|
'cancel_vacay_invite',
|
|
'accept_vacay_invite',
|
|
'decline_vacay_invite',
|
|
'cancel_collection_invite',
|
|
'accept_collection_invite',
|
|
'decline_collection_invite',
|
|
]);
|
|
const SHARE_LIKE = /share|invite|feed/;
|
|
|
|
/**
|
|
* Read-only tools that still wait for the user: they fetch an address that
|
|
* came from the web or a message. The packages add theirs in their cards.
|
|
*/
|
|
export const HELD_READS: ReadonlySet<string> = new Set([
|
|
'resolve_maps_url',
|
|
'preview_google_maps_route',
|
|
'preview_google_maps_walk',
|
|
...PACKAGE_HELD_READS,
|
|
]);
|
|
|
|
export function isOfferedTool(name: string): boolean {
|
|
return !(name in ASSISTANT_DENIED_TOOLS);
|
|
}
|
|
|
|
/** The argument a Studio conversation pins on every tool that takes it, as a trip conversation pins `tripId`. */
|
|
export const JOURNEY_PINNED_ARG = 'journeyId';
|
|
|
|
/** The controllers of the book itself: their reads, and their writes for someone who may change the book. */
|
|
const STUDIO_CONTROLLERS: ReadonlySet<string> = new Set([
|
|
'JourneyBookMcp',
|
|
'JourneyBookPhotosMcp',
|
|
'JourneyBookDesignMcp',
|
|
]);
|
|
|
|
/** The controllers whose reads a Studio conversation also gets: the journey, its map and its tracks. */
|
|
const JOURNEY_READ_CONTROLLERS: ReadonlySet<string> = new Set(['JourneyMcp', 'JourneyMapMcp', 'JourneyTracksMcp']);
|
|
|
|
/**
|
|
* Whether a registered tool is one of the book's own. A trip conversation
|
|
* leaves these out by their controller as well as by name, so a book tool
|
|
* added later never reaches a trip chat through the journey group.
|
|
*/
|
|
export function isStudioController(className: string | undefined): boolean {
|
|
return className !== undefined && STUDIO_CONTROLLERS.has(className);
|
|
}
|
|
|
|
/**
|
|
* What is wrong with the book tools against the registry: one that is not
|
|
* listed above as a Studio tool (or as the undo target), so the denylist and
|
|
* the Studio's offer no longer tell the same story.
|
|
*/
|
|
export function checkStudioTools(listing: Iterable<Pick<McpRegistryListing, 'kind' | 'name' | 'className'>>): string[] {
|
|
const problems: string[] = [];
|
|
for (const entry of listing) {
|
|
if (entry.kind === 'tool' && isStudioController(entry.className) && !(entry.name in ASSISTANT_DENIED_TOOLS)) {
|
|
problems.push(`book tool "${entry.name}" is not listed as a Studio tool`);
|
|
}
|
|
}
|
|
return problems;
|
|
}
|
|
|
|
/**
|
|
* Whether a Studio conversation attaches a registered tool: one of the book's
|
|
* or the journey's, and none the denylist keeps from the assistant, the book
|
|
* tools a trip chat goes without excepted (`restore_book_page` stays out: it
|
|
* is an undo target only).
|
|
*/
|
|
export function isOfferedInJourney(name: string, className: string | undefined): boolean {
|
|
if (name in ASSISTANT_DENIED_TOOLS && !(name in STUDIO_ONLY_TOOLS)) return false;
|
|
return isStudioController(className) || (className !== undefined && JOURNEY_READ_CONTROLLERS.has(className));
|
|
}
|
|
|
|
/**
|
|
* The controllers whose reads work only for someone who may change the book:
|
|
* a design draft is its editor's, so a viewer's design_book, revise_book_design
|
|
* and get_book_design could only refuse.
|
|
*/
|
|
const EDITOR_READ_CONTROLLERS: ReadonlySet<string> = new Set(['JourneyBookDesignMcp']);
|
|
|
|
/**
|
|
* Whether a Studio conversation keeps an attached tool once its schema and
|
|
* annotations are known. Only tools that work on the conversation's journey
|
|
* (they take the `journeyId` the server pins) stay, so the conversation never
|
|
* reaches another journey; of those every read but the design draft's, which,
|
|
* like the book's writes, go only to someone who may change the book. The
|
|
* journey's own writes (entries, photos, its trips) stay with the journey page.
|
|
*/
|
|
export function keptInJourney(
|
|
className: string | undefined,
|
|
kind: 'read' | 'write',
|
|
pinned: boolean,
|
|
canWrite: boolean,
|
|
): boolean {
|
|
if (!pinned) return false;
|
|
if (kind === 'read') return canWrite || className === undefined || !EDITOR_READ_CONTROLLERS.has(className);
|
|
return canWrite && isStudioController(className);
|
|
}
|
|
|
|
/**
|
|
* The arguments that name a trip or a journey, as the tools spell them: the
|
|
* collections' copy takes `trip_id`, a new journey its `trip_ids`, a Dawarich
|
|
* stay taken into a journal its `journalId`.
|
|
*/
|
|
const TRIP_OR_JOURNEY_ARGS: ReadonlySet<string> = new Set([
|
|
PINNED_ARG,
|
|
JOURNEY_PINNED_ARG,
|
|
'trip_id',
|
|
'trip_ids',
|
|
'journey_id',
|
|
'journalId',
|
|
]);
|
|
|
|
/**
|
|
* The controllers of a journey's own content, whose every write works on one
|
|
* journey, also when it names only a part of it (an entry by its `entryId`).
|
|
*/
|
|
const JOURNEY_WRITE_CONTROLLERS: ReadonlySet<string> = new Set([
|
|
'JourneyMcp',
|
|
'JourneyPhotoLinksMcp',
|
|
'JourneyMapMcp',
|
|
'JourneyTracksMcp',
|
|
'JourneyRecordingsMcp',
|
|
'JourneyDayImportMcp',
|
|
'TripJournalLinkMcp',
|
|
]);
|
|
|
|
/**
|
|
* The journey writes the home chat keeps although they name trips or a
|
|
* journey: starting a journal (its trips are checked one by one by the tool,
|
|
* as for any MCP client), and deleting one, which its own chat leaves out
|
|
* because the conversation goes with it; the tool refuses everyone but the
|
|
* owner.
|
|
*/
|
|
const HOME_JOURNEY_WRITES: ReadonlySet<string> = new Set(['create_journey', 'delete_journey']);
|
|
|
|
/**
|
|
* Whether the home chat (no one trip, no one journey) keeps an attached tool
|
|
* once its schema and annotations are known: every read, a trip's or a
|
|
* journey's too, on the id the model names (the tool itself checks that the
|
|
* user may read it, as for any MCP client); and the writes that take neither
|
|
* a trip nor a journey (the atlas, the vacation planner, collections, the
|
|
* tour library, the settings), with a journal's start and its deletion. A
|
|
* trip's own changes belong in that trip's chat, which the home chat offers
|
|
* instead (open_trip_chat); a journal's in the chat on its page
|
|
* (open_journey_chat).
|
|
*/
|
|
export function keptAtHome(
|
|
kind: 'read' | 'write',
|
|
schemaArgs: Iterable<string>,
|
|
className: string | undefined,
|
|
name = '',
|
|
): boolean {
|
|
if (kind === 'read') return true;
|
|
if (HOME_JOURNEY_WRITES.has(name)) return true;
|
|
if (className !== undefined && JOURNEY_WRITE_CONTROLLERS.has(className)) return false;
|
|
for (const arg of schemaArgs) if (TRIP_OR_JOURNEY_ARGS.has(arg)) return false;
|
|
return true;
|
|
}
|
|
|
|
/** What is wrong with the denylist against the registry: a sharing tool that slipped through. */
|
|
export function checkDenylist(names: Iterable<string>): string[] {
|
|
const problems: string[] = [];
|
|
for (const name of names) {
|
|
if (SHARE_LIKE.test(name) && isOfferedTool(name) && !SHARE_LIKE_SAFE.has(name)) {
|
|
problems.push(`"${name}" shares, invites or publishes; deny it or list it as safe`);
|
|
}
|
|
}
|
|
return problems;
|
|
}
|
|
|
|
type ToolGroups = Readonly<Record<string, { about: string; controllers: readonly string[] }>>;
|
|
|
|
/**
|
|
* The tool groups a turn can load, by the MCP controller that registers the
|
|
* tools, each with the words the model reads to pick it. A controller not
|
|
* listed here, nor added by a package (`toolControllers` in its cards),
|
|
* belongs to the core, which every step offers.
|
|
*/
|
|
const CORE_TOOL_GROUPS: ToolGroups = {
|
|
tours: {
|
|
about:
|
|
'Tours: hikes (also over several days in stages), city walks, bike tours (road, gravel, mountain bike), ' +
|
|
'runs (road and trail), rides, paddling and ski and winter tours; plan and save every one of them, change ' +
|
|
'and export them (hikes with their heights and SAC grades), round hikes of a wished length and other ' +
|
|
'ways for one leg, search along a tour, check off a city walk under way, the recorded tracks and tour ' +
|
|
'stats, their packing, tours in collections, the tour library, wanderer trails and imports from GPX ' +
|
|
'files and Google Maps walks.',
|
|
controllers: [
|
|
'ToursMcp',
|
|
'CityWalkMcp',
|
|
'HikePlanMcp',
|
|
'TourPlanMcp',
|
|
'TourChangeMcp',
|
|
'TourChangeUndoMcp',
|
|
'TourLibraryMcp',
|
|
'TourPackingMcp',
|
|
'TourActivitiesMcp',
|
|
'TourActivityStatsMcp',
|
|
'TourWalkImportMcp',
|
|
'TourStopsMcp',
|
|
'CollectionToursMcp',
|
|
'PaddleRoutingMcp',
|
|
'SkiRoutingMcp',
|
|
'HikeWaysMcp',
|
|
'ToursWandererMcp',
|
|
],
|
|
},
|
|
roadtrip: {
|
|
about:
|
|
'Road trips and transit: the driving route and its stops, where each day ends, charging, hazards, ' +
|
|
'public transport journeys and driving routes imported from Google Maps.',
|
|
controllers: [
|
|
'RoadtripMcp',
|
|
'RoadtripPlanningMcp',
|
|
'RoadtripPreferencesMcp',
|
|
'RoadtripHazardsMcp',
|
|
'ChargingMcp',
|
|
'TransitMcp',
|
|
],
|
|
},
|
|
journey: {
|
|
about:
|
|
'Journeys (the travel journal): entries, photos, the journal linked to this trip, its map and GPX tracks, ' +
|
|
'location history and the recorded days.',
|
|
controllers: [
|
|
'JourneyMcp',
|
|
'JourneyPhotoLinksMcp',
|
|
'JourneyMapMcp',
|
|
'JourneyTracksMcp',
|
|
'JourneyBookMcp',
|
|
'JourneyBookPhotosMcp',
|
|
'JourneyRecordingsMcp',
|
|
'JourneyDayImportMcp',
|
|
'TripJournalLinkMcp',
|
|
'MemoriesMcp',
|
|
'DawarichMcp',
|
|
],
|
|
},
|
|
vacay: {
|
|
about: 'Vacation planner: vacation days per year, public and school holidays, shared calendars.',
|
|
controllers: ['VacayMcp', 'SchoolHolidaysMcp'],
|
|
},
|
|
atlas: {
|
|
about: 'Atlas: visited countries and regions, the bucket list, and both checked against the Dawarich recordings.',
|
|
controllers: ['AtlasMcp', 'DawarichAtlasMcp'],
|
|
},
|
|
collections: {
|
|
about: 'Collections: saved places across trips, their labels and ratings.',
|
|
controllers: ['CollectionsMcp'],
|
|
},
|
|
collab: { about: 'Trip chat: notes, polls and messages to the people on the trip.', controllers: ['CollabMcp'] },
|
|
files: {
|
|
about: 'Files and imports: the trip files, document sync, flights from AirTrail.',
|
|
controllers: ['FilesMcp', 'DocSyncMcp', 'ReservationImportMcp', 'AirtrailMcp'],
|
|
},
|
|
account: {
|
|
about: 'The user: notifications and display settings.',
|
|
controllers: ['NotificationsMcp', 'SettingsMcp'],
|
|
},
|
|
plugins: {
|
|
about: 'Places and points of interest from installed plugins.',
|
|
controllers: ['PluginPoisMcp', 'PluginSearchMcp'],
|
|
},
|
|
};
|
|
|
|
/**
|
|
* The groups with the controllers the packages added to them. A package that
|
|
* names a group this file does not know, or a controller a group lists
|
|
* already, stops the server at load.
|
|
*/
|
|
export function withPackageControllers(
|
|
core: ToolGroups,
|
|
added: Readonly<Record<string, readonly string[]>>,
|
|
): ToolGroups {
|
|
const groups = Object.fromEntries(Object.entries(core).map(([group, value]) => [group, { ...value }]));
|
|
const listed = new Set(Object.values(core).flatMap((group) => group.controllers));
|
|
for (const [group, controllers] of Object.entries(added)) {
|
|
const known = groups[group];
|
|
if (!known) throw new Error(`Assistant tool groups: no group "${group}" for ${controllers.join(', ')}`);
|
|
const twice = controllers.find((controller) => listed.has(controller));
|
|
if (twice) throw new Error(`Assistant tool groups: controller "${twice}" is listed already`);
|
|
known.controllers = [...known.controllers, ...controllers];
|
|
}
|
|
return groups;
|
|
}
|
|
|
|
export const ASSISTANT_TOOL_GROUPS = withPackageControllers(CORE_TOOL_GROUPS, PACKAGE_TOOL_CONTROLLERS);
|
|
|
|
const GROUP_OF_CONTROLLER = new Map(
|
|
Object.entries(ASSISTANT_TOOL_GROUPS).flatMap(([group, { controllers }]) =>
|
|
controllers.map((controller) => [controller, group] as const),
|
|
),
|
|
);
|
|
|
|
/** The group a registered tool loads with; null for the core. */
|
|
export function groupOf(entry: Pick<McpRegistryListing, 'className'>): string | null {
|
|
return GROUP_OF_CONTROLLER.get(entry.className) ?? null;
|
|
}
|
|
|
|
/** The server's own step that loads a group's tools for the rest of the turn. */
|
|
export const USE_TOOLS_TOOL = 'use_addon_tools';
|
|
|
|
/** The step's description: the groups, and what needs nothing loaded in this kind of conversation. */
|
|
function useToolsDescription(core: string): string {
|
|
return (
|
|
'Load the tools of more parts of TREK for the rest of this turn. Call it before working with any of: ' +
|
|
Object.entries(ASSISTANT_TOOL_GROUPS)
|
|
.map(([group, { about }]) => `"${group}" (${about})`)
|
|
.join('; ') +
|
|
`. ${core}`
|
|
);
|
|
}
|
|
|
|
const USE_TOOLS_PARAMETERS: AiToolSpec['parameters'] = {
|
|
type: 'object',
|
|
properties: {
|
|
groups: {
|
|
type: 'array',
|
|
items: { type: 'string', enum: Object.keys(ASSISTANT_TOOL_GROUPS) },
|
|
minItems: 1,
|
|
},
|
|
},
|
|
required: ['groups'],
|
|
additionalProperties: false,
|
|
};
|
|
|
|
/** The same step in the home chat, where the core reads trips by the id the model passes. */
|
|
export const HOME_USE_TOOLS_SPEC: AiToolSpec = {
|
|
name: USE_TOOLS_TOOL,
|
|
description: useToolsDescription(
|
|
'Reading the trips (list_trips, and a trip by its id: days, places, bookings, packing, to-dos, budget, weather) ' +
|
|
'needs nothing loaded.',
|
|
),
|
|
parameters: USE_TOOLS_PARAMETERS,
|
|
};
|
|
|
|
export const USE_TOOLS_SPEC: AiToolSpec = {
|
|
name: USE_TOOLS_TOOL,
|
|
description: useToolsDescription(
|
|
'The trip itself (days, places, bookings, packing, to-dos, budget, weather, search) needs nothing loaded.',
|
|
),
|
|
parameters: {
|
|
type: 'object',
|
|
properties: {
|
|
groups: {
|
|
type: 'array',
|
|
items: { type: 'string', enum: Object.keys(ASSISTANT_TOOL_GROUPS) },
|
|
minItems: 1,
|
|
},
|
|
},
|
|
required: ['groups'],
|
|
additionalProperties: false,
|
|
},
|
|
};
|