crow-central-agency 0.26.7 → 0.26.8

package/README.md

@@ -107,6 +107,9 @@ See `.env.example` for the full list, including:
 - `FEED_TEXT_GENERATION_*` — optional OpenAI-compatible endpoint used by the feed manager to summarize feed items into a consistent length for better agent consumption.
 - `FEED_MAX_SUMMARIZATION_ITEMS` — cap on items summarized per refresh (default: `50`). Items left unsummarized become retry candidates on the next refresh; when the retry backlog exceeds the cap, retries are skipped so a feed isn't permanently blocked by hundreds or thousands of stuck unsummarized items.
 - `AUDIO_GENERATION_*` — optional Gemini TTS configuration that powers the play-message button on the agent console. See [Audio generation](#audio-generation) below.
+- `PLACES_DEFAULT_SOURCE` — default provider for the Places tools when a lookup doesn't request one explicitly: `OSM` (default, no key needed) or `GOOGLE`. `GOOGLE` requires `GOOGLE_PLACES_API_KEY`; without it, lookups fall back to OSM. See [Places](#places) below.
+- `GOOGLE_PLACES_API_KEY` — Google API key that registers the Google Places adapter alongside the default OSM source. See [Places](#places) below.
+- `PHOTON_API_URL` / `OVERPASS_INTERPRETER_URL` — override the geocoding / nearby-search endpoints the OSM places source calls (default to the public Photon and Overpass instances).
 - `GOOGLE_CONNECTOR_CLIENT_ID` / `GOOGLE_CONNECTOR_CLIENT_SECRET` / `CONNECTOR_CALLBACK_URL` — OAuth credentials for the Google connector. Required if you want agents to access Gmail / Calendar / Contacts. See [Connectors](#connectors) below.
 - `OAUTH_PENDING_STATE_TTL_MS` — how long an unfinished OAuth flow stays valid before being swept (default: `600_000`, i.e. 10 minutes).
 - `OTEL_*` — optional OpenTelemetry export.
@@ -139,6 +142,73 @@ The `AUDIO_GENERATION_API_KEY` must be a Google API key with access to the
 You can use the same key as `TEXT_GENERATION_API_KEY` if that is also a
 Gemini-backed configuration, but the two are read independently.
 
+## Places
+
+The **Places** MCP server gives agents location tools — `geocode_place`,
+`search_nearby_places`, and `get_place_details`. It is enabled per-agent from
+the **MCP Servers** section of the agent editor.
+
+Two providers back these tools:
+
+- **OSM** (default) — uses the public OpenStreetMap-based services (Photon for
+  geocoding, Overpass for nearby search). No API key required, so the Places
+  tools work out of the box.
+- **GOOGLE** — uses the Google Places API (New) and Geocoding API for richer
+  results. Opt in by setting `GOOGLE_PLACES_API_KEY`.
+
+`PLACES_DEFAULT_SOURCE` selects which provider serves lookups that don't name a
+source explicitly (`OSM` or `GOOGLE`, defaulting to `OSM`). When
+`GOOGLE_PLACES_API_KEY` is set, the Google adapter is registered alongside OSM;
+if `PLACES_DEFAULT_SOURCE=GOOGLE` is set without a key, lookups fall back to OSM.
+
+### Configuration
+
+```bash
+PLACES_DEFAULT_SOURCE=GOOGLE
+GOOGLE_PLACES_API_KEY=<your Google API key>
+```
+
+### Getting a Google Places API key
+
+The key is a plain Google API key (not an OAuth client — unrelated to the
+Google connector setup below).
+
+**1. Sign in to Google Cloud Console.**
+
+Go to [console.cloud.google.com](https://console.cloud.google.com/) and select
+(or create) a project. Unlike the OAuth connector, the Places and Geocoding
+APIs are **paid** and require a billing account on the project. Google provides
+a recurring monthly free allotment, but you must still enable billing to use
+the key.
+
+**2. Enable the required APIs.**
+
+Open **APIs & Services → Library** and enable both:
+
+- **Places API (New)** — powers `search_nearby_places` and `get_place_details`.
+- **Geocoding API** — powers reverse geocoding for `geocode_place`.
+
+Click each result, then click **Enable**.
+
+**3. Create the API key.**
+
+Open **APIs & Services → Credentials → Create Credentials → API key**. Copy the
+generated key.
+
+> [!NOTE]
+> Restrict the key to just the **Places API (New)** and **Geocoding API** under
+> the key's **API restrictions** so a leaked key can't be used against other
+> Google services.
+
+**4. Add the key to your `.env` and restart Crow.**
+
+```bash
+GOOGLE_PLACES_API_KEY=<paste the API key>
+PLACES_DEFAULT_SOURCE=GOOGLE
+```
+
+Restart the server so it picks up the new env vars.
+
 ## Connectors
 
 Connectors are a framework-level capability - they are not tools agents call

package/dist/_shared/schemas/agent.schema.js

@@ -317,7 +317,8 @@ export const UpdateAgentInputSchema = z.object({
     workspace: z.string().optional(),
     persona: z.string().optional(),
     model: z.string().optional(),
-    effort: ReasoningEffortSchema.optional(),
+    // null explicitly clears the effort (back to provider default); undefined leaves it unchanged.
+    effort: ReasoningEffortSchema.nullish(),
     permissionMode: PermissionModeSchema.optional(),
     settingSources: z.array(SettingSourceSchema).optional(),
     settingSourceConfig: SettingSourceConfigInputSchema.optional(),

package/dist/config/env.js

@@ -2,6 +2,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { expandPath } from "../utils/fs-utils.js";
+import { PLACES_SOURCE } from "../services/places/places-manager.types.js";
 const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = path.resolve(CONFIG_DIR, "..");
 const DEFAULT_STATIC_DIR = path.join(DIST_DIR, "public");
@@ -15,6 +16,9 @@ function getBoolean(key) {
     const value = process.env[key]?.trim().toLowerCase();
     return value === "true" || value === "1";
 }
+function resolvePlacesSource(key) {
+    return process.env[key]?.trim().toUpperCase() === PLACES_SOURCE.GOOGLE ? PLACES_SOURCE.GOOGLE : PLACES_SOURCE.OSM;
+}
 function readRequired(key) {
     const value = process.env[key]?.trim();
     if (!value) {
@@ -74,6 +78,8 @@ export const env = {
     GMAIL_CHECK_INTERVAL_IN_MINUTES: getOptionalNumber("GMAIL_CHECK_INTERVAL_IN_MINUTES"),
     PHOTON_API_URL: getOptional("PHOTON_API_URL") ?? "https://photon.komoot.io",
     OVERPASS_INTERPRETER_URL: getOptional("OVERPASS_INTERPRETER_URL") ?? "https://overpass-api.de/api/interpreter",
+    PLACES_DEFAULT_SOURCE: resolvePlacesSource("PLACES_DEFAULT_SOURCE"),
+    GOOGLE_PLACES_API_KEY: getOptional("GOOGLE_PLACES_API_KEY"),
 };
 /**
  * Eagerly validate all required environment variables. Call once during boot

package/dist/mcp/places/geocode-place.js

@@ -1,20 +1,40 @@
 import { z } from "zod";
+import { PLACES_SOURCE } from "../../services/places/places-manager.types.js";
 import { getErrorToolResult, textToolResult } from "../tool-utils.js";
 import { formatPlaceSummary } from "./places-format-utils.js";
 const DEFAULT_GEOCODE_LIMIT = 10;
 const MAX_GEOCODE_LIMIT = 25;
 export const GEOCODE_PLACE_TOOL_NAME = "geocode_place";
+const NEUTRAL_DESCRIPTION = "Resolve a free-text query - a place name, full address, or landmark - to matching places. " +
+    "Use get_place_details on a returned id for opening hours, contact info, and other attributes.";
+const NEUTRAL_RESULT_GUIDANCE = "Refine with a more specific name, address, or the city/country disambiguators if needed.";
+const DESCRIPTION_BY_SOURCE = {
+    [PLACES_SOURCE.GOOGLE]: "Resolve a free-text query to matching places. Accepts a place name, a full address, a landmark, or a " +
+        "natural-language / descriptive POI search (e.g. 'rooftop bars in Shibuya'). " +
+        "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
+    [PLACES_SOURCE.OSM]: "Resolve a free-text query to matching places. Best results come from a precise name or full address; " +
+        "descriptive or category-style queries degrade - for category discovery use search_nearby_places. " +
+        "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
+};
+const RESULT_GUIDANCE_BY_SOURCE = {
+    [PLACES_SOURCE.GOOGLE]: "Phrase queries in natural language (names, full addresses, or descriptive POI searches) for stronger matches.",
+    [PLACES_SOURCE.OSM]: "Use a precise name or full address; descriptive or category queries return weak matches.",
+};
+function selectForSource(map, source, fallback) {
+    return map[source] ?? fallback;
+}
 export function getGeocodePlaceToolConfig(placesManager) {
+    const defaultSource = placesManager.getDefaultSource();
+    const description = selectForSource(DESCRIPTION_BY_SOURCE, defaultSource, NEUTRAL_DESCRIPTION);
+    const resultGuidance = selectForSource(RESULT_GUIDANCE_BY_SOURCE, defaultSource, NEUTRAL_RESULT_GUIDANCE);
     const inputSchema = {
-        name: z.string().min(1).optional().describe("Proper-noun name of a specific place or business."),
-        street: z.string().min(1).optional().describe("Street address, including house number when known."),
-        city: z.string().min(1).optional().describe("City, town, or locality. Example: 'London', 'Paris'."),
-        postcode: z.string().min(1).optional().describe("Postal / ZIP code."),
+        query: z.string().min(1).describe("A place name, a full address, or a landmark (e.g. 'Eiffel Tower')."),
+        city: z.string().min(1).optional().describe("City, town, or locality to disambiguate the query."),
         country: z
             .string()
             .min(1)
             .optional()
-            .describe("Country name or ISO 3166-1 alpha-2 code (e.g. 'France' or 'FR'). Use to disambiguate same-named places across countries."),
+            .describe("Country name or ISO 3166-1 alpha-2 code (e.g. 'France' or 'FR') to disambiguate same-named places."),
         nearLatitude: z
             .number()
             .min(-90)
@@ -31,14 +51,14 @@ export function getGeocodePlaceToolConfig(placesManager) {
             .describe(`Max results to return (default ${DEFAULT_GEOCODE_LIMIT}, max ${MAX_GEOCODE_LIMIT}).`),
     };
     const handler = async (args) => {
-        const queryParts = [args.name, args.street, args.city, args.postcode, args.country]
+        if ((args.nearLatitude === undefined) !== (args.nearLongitude === undefined)) {
+            return textToolResult(["nearLatitude and nearLongitude must both be provided or both omitted."], true);
+        }
+        const queryParts = [args.query, args.city, args.country]
             .map((part) => part?.trim())
             .filter((part) => part !== undefined && part.length > 0);
         if (queryParts.length === 0) {
-            return textToolResult(["At least one of name, street, city, postcode, or country must be provided."], true);
-        }
-        if ((args.nearLatitude === undefined) !== (args.nearLongitude === undefined)) {
-            return textToolResult(["nearLatitude and nearLongitude must both be provided or both omitted."], true);
+            return textToolResult(["query must contain non-whitespace text."], true);
         }
         const queryText = queryParts.join(", ");
         try {
@@ -51,11 +71,11 @@ export function getGeocodePlaceToolConfig(placesManager) {
                 limit: args.limit ?? DEFAULT_GEOCODE_LIMIT,
             });
             if (places.length === 0) {
-                return textToolResult([`No places found matching "${queryText}".`]);
+                return textToolResult([`No places found matching "${queryText}".`, resultGuidance]);
             }
             const header = `[Geocode results: ${places.length} for "${queryText}"]`;
             const body = places.map(formatPlaceSummary).join("\n");
-            return textToolResult([header, body]);
+            return textToolResult([header, body, resultGuidance]);
         }
         catch (error) {
             return getErrorToolResult(error, "Failed to geocode place.");
@@ -63,12 +83,7 @@ export function getGeocodePlaceToolConfig(placesManager) {
     };
     const config = {
         name: GEOCODE_PLACE_TOOL_NAME,
-        description: [
-            "Resolve a known place to coordinates: a named landmark, business, or specific street address. ",
-            "Provide whichever structured fields you have - the more you fill, the more precise the match. ",
-            "Not a discovery tool: for 'cafes near me', 'good restaurants', or any category / subjective query, use search_nearby_places instead. ",
-            "Use get_place_details on a returned id for opening hours, contact info, and other attributes.",
-        ].join(""),
+        description,
         inputSchema,
         handler,
     };

package/dist/mcp/places/places-format-utils.js

@@ -1,4 +1,4 @@
-import { WEEKDAY, } from "../../services/places/places-manager.types.js";
+import { BUSINESS_STATUS, WEEKDAY, } from "../../services/places/places-manager.types.js";
 const WEEKDAY_LABEL = {
     [WEEKDAY.MONDAY]: "Monday",
     [WEEKDAY.TUESDAY]: "Tuesday",
@@ -19,6 +19,12 @@ export function formatPlaceSummary(place) {
     if (place.address !== undefined && place.address.length > 0) {
         lines.push(`    - Address: ${place.address}`);
     }
+    if (place.businessStatus !== undefined && place.businessStatus !== BUSINESS_STATUS.OPERATIONAL) {
+        lines.push(`    - Business status: ${place.businessStatus}`);
+    }
+    if (place.mapsUrl !== undefined && place.mapsUrl.length > 0) {
+        lines.push(`    - Map: ${place.mapsUrl}`);
+    }
     return lines.join("\n");
 }
 /** Full-detail block returned by `places_get_details`. Layers attributes on top of the summary. */
@@ -48,6 +54,12 @@ export function formatPlaceDetails(details) {
     if (details.wheelchairAccess !== undefined) {
         lines.push(`    - Wheelchair access: ${details.wheelchairAccess}`);
     }
+    if (details.transit !== undefined && details.transit.lines.length > 0) {
+        lines.push("    - Transit lines:");
+        for (const line of details.transit.lines) {
+            lines.push(`        ${formatTransitLine(line)}`);
+        }
+    }
     if (details.description !== undefined && details.description.length > 0) {
         lines.push("    - Description:");
         for (const descriptionLine of details.description.split(/\r?\n/)) {
@@ -56,6 +68,16 @@ export function formatPlaceDetails(details) {
     }
     return lines.join("\n");
 }
+function formatTransitLine(line) {
+    let formatted = `${line.vehicleType}  ${line.shortName ?? line.name}`;
+    if (line.shortName !== undefined && line.shortName !== line.name) {
+        formatted += ` (${line.name})`;
+    }
+    if (line.operator !== undefined) {
+        formatted += ` — ${line.operator}`;
+    }
+    return formatted;
+}
 function formatOpeningHoursLines(hours) {
     if (hours.alwaysOpen) {
         return ["Open 24/7"];