@ixo/oracle-runtime-workers 0.2.0

package/src/core/plugins/weather/weather-sub-agent.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { tool } from '../../../plugin-api/tool-helper';
+import type { PluginSubAgent, PluginTool } from '../../../plugin-api/types';
+import type { Units } from './weather-client';
+import { buildForecastTool, type LastQueryStore } from './weather-tools';
+
+function buildRecommendOutfitTool(): PluginTool {
+  return tool(
+    async (rawArgs) => {
+      const { temp_c, conditions } = z
+        .object({ temp_c: z.number(), conditions: z.string() })
+        .parse(rawArgs);
+      const wet = ['rain', 'showers', 'thunderstorm', 'snow'].some((k) =>
+        conditions.toLowerCase().includes(k),
+      );
+      let layer: string;
+      if (temp_c >= 25) layer = 'a t-shirt and shorts';
+      else if (temp_c >= 18) layer = 'a t-shirt';
+      else if (temp_c >= 10) layer = 'a light jacket';
+      else if (temp_c >= 0) layer = 'a warm coat and a scarf';
+      else layer = 'a heavy winter coat, gloves, and a hat';
+      return `Wear ${layer}${wet ? ' and bring an umbrella' : ''}.`;
+    },
+    {
+      name: 'recommend_outfit',
+      description:
+        'Given a temperature in Celsius and short conditions string, return a one-line outfit suggestion.',
+      schema: z.object({
+        temp_c: z.number().describe('Temperature in Celsius.'),
+        conditions: z.string().describe('e.g. "rain", "clear", "snow".'),
+      }),
+    },
+  );
+}
+
+const PROMPT = [
+  'You are the Weather Planner Agent. You decide whether the user needs a',
+  'jacket / umbrella / etc. for a place and time.',
+  '',
+  'Workflow:',
+  '1. Call get_weather_forecast with the city (and days if specified).',
+  '2. Pick the most relevant day. If temperatures are Fahrenheit, convert to',
+  '   Celsius: c = (f - 32) * 5/9.',
+  "3. Call recommend_outfit with that day's max temp (Celsius) and conditions.",
+  '4. Reply with ONE sentence combining the forecast and the outfit advice,',
+  '   e.g. "Berlin tomorrow: 14°C with rain — wear a light jacket and bring an umbrella."',
+  '',
+  'Rules: ALWAYS call the tools. Never invent forecasts. If a tool returns an',
+  'error string, return it verbatim.',
+].join('\n');
+
+export function buildWeatherPlannerSubAgent(
+  defaultUnits: Units,
+  store: LastQueryStore,
+): PluginSubAgent {
+  return {
+    name: 'weather_planner_agent',
+    description:
+      'Combines a forecast lookup with an outfit recommendation. Use for "should I bring a jacket to X tomorrow?" / "what should I wear in Y?".',
+    systemPrompt: PROMPT,
+    tools: [buildForecastTool(defaultUnits, store), buildRecommendOutfitTool()],
+    model: 'subagent',
+    forwardTools: true,
+  };
+}

package/src/core/plugins/weather/weather-tools.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { tool } from '../../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../../plugin-api/types';
+import { getCurrentWeather, getForecast, type Units } from './weather-client';
+
+export interface LastWeatherQuery {
+  city: string;
+  latitude: number;
+  longitude: number;
+  queriedAt: string;
+}
+export type LastQueryStore = Map<string, LastWeatherQuery>;
+
+const recordLast = (
+  store: LastQueryStore,
+  sessionId: string,
+  result: { city: string; latitude: number; longitude: number },
+): void => {
+  store.set(sessionId, {
+    city: result.city,
+    latitude: result.latitude,
+    longitude: result.longitude,
+    queriedAt: new Date().toISOString(),
+  });
+};
+
+/** Boot-time tool — reads default units from plugin config. */
+export function buildCurrentWeatherTool(
+  defaultUnits: Units,
+  store: LastQueryStore,
+): PluginTool {
+  return tool(
+    async (rawArgs, ctx: RuntimeContext) => {
+      const { city } = z.object({ city: z.string().min(1) }).parse(rawArgs);
+      const result = await getCurrentWeather(
+        city,
+        defaultUnits,
+        ctx.abortSignal,
+      );
+      if (!result) {
+        return `Could not find weather for "${city}". Try a more specific city name.`;
+      }
+      recordLast(store, ctx.session.id, result);
+      return JSON.stringify(result);
+    },
+    {
+      name: 'get_current_weather',
+      description:
+        'Get the current weather for a city. Returns temperature, wind speed (km/h), conditions, and coordinates.',
+      schema: z.object({
+        city: z.string().min(1).describe('City name, e.g. "Berlin".'),
+      }),
+    },
+  );
+}
+
+/** Per-request tool — reads the user's timezone off `rtCtx`. */
+export function buildForecastTool(
+  defaultUnits: Units,
+  store: LastQueryStore,
+): PluginTool {
+  return tool(
+    async (rawArgs, ctx: RuntimeContext) => {
+      const { city, days } = z
+        .object({
+          city: z.string().min(1),
+          days: z.number().int().min(1).max(7).optional(),
+        })
+        .parse(rawArgs);
+      const tz =
+        ctx.user.timezone && ctx.user.timezone.length > 0
+          ? ctx.user.timezone
+          : 'auto';
+      const result = await getForecast(
+        city,
+        days ?? 3,
+        defaultUnits,
+        tz,
+        ctx.abortSignal,
+      );
+      if (!result) {
+        return `Could not find a forecast for "${city}". Try a more specific city name.`;
+      }
+      recordLast(store, ctx.session.id, result);
+      return JSON.stringify(result);
+    },
+    {
+      name: 'get_weather_forecast',
+      description:
+        'Get a daily weather forecast for a city (up to 7 days). Returns max/min temp + conditions per day. Uses the user timezone when available, else auto-detects.',
+      schema: z.object({
+        city: z.string().min(1).describe('City name.'),
+        days: z
+          .number()
+          .int()
+          .min(1)
+          .max(7)
+          .optional()
+          .describe('Forecast horizon in days (1-7). Defaults to 3.'),
+      }),
+    },
+  );
+}

package/src/core/plugins/weather/weather.plugin.ts

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+import {
+  OraclePlugin,
+  type PluginRoute,
+} from '../../../plugin-api/oracle-plugin';
+import type {
+  AgentMiddleware,
+  AuthExcludedRoute,
+  PluginContext,
+  PluginManifest,
+  PluginSubAgent,
+  PluginTool,
+  RuntimeContext,
+} from '../../../plugin-api/types';
+import { getCurrentWeather, type Units } from './weather-client';
+import { buildWeatherMiddleware } from './weather-middleware';
+import { buildWeatherPlannerSubAgent } from './weather-sub-agent';
+import {
+  buildCurrentWeatherTool,
+  buildForecastTool,
+  type LastQueryStore,
+  type LastWeatherQuery,
+} from './weather-tools';
+
+const NAME = 'weather';
+const VERSION = '0.1.0';
+
+const configSchema = z.object({
+  WEATHER_DEFAULT_UNITS: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+});
+
+const manifest: PluginManifest = {
+  title: 'Weather',
+  summary:
+    'ALWAYS use the provided weather tools to answer user questions about current weather, forecasts, or outfit recommendations. Do NOT attempt to answer from prior knowledge or assumptions—call the appropriate tool for every weather-related request to obtain up-to-date results. Powered by Open-Meteo (no API key required).',
+  whenToUse: [
+    'Whenever asked about current weather, temperature, precipitation, wind, or other weather conditions in any city or region.',
+    'Any question related to forecasts (e.g., today, tomorrow, next week, weekend, specific date) for any location.',
+    'Whenever the user asks "what should I wear", "do I need an umbrella", "do I need a jacket", or similar outfit/clothing guidance—ALWAYS use the weather tools to get real forecast data first.',
+    'If the user inquires about whether to bring weather-related items (umbrella, jacket, sunglasses, etc.), make sure to call the relevant weather tool(s) before providing recommendations.',
+  ],
+  whenNotToUse: [
+    'Questions about historical or long-term climate data (the tools provide only current or short-term forecast information).',
+    'Locations smaller than city-level precision (e.g., a specific street address)—weather will be provided for the nearest city centroid.',
+    'If the user asks about unrelated topics not connected to weather, temperature, climate, or outfit recommendations.',
+  ],
+  examples: [
+    {
+      user: "What's the weather in Berlin?",
+      tool: 'get_current_weather',
+      args: { city: 'Berlin' },
+    },
+    {
+      user: 'Forecast for Tokyo this week.',
+      tool: 'get_weather_forecast',
+      args: { city: 'Tokyo', days: 7 },
+    },
+    {
+      user: 'Should I bring a jacket to Berlin tomorrow?',
+      tool: 'call_weather_planner_agent',
+      args: {
+        task: 'Decide whether the user needs a jacket in Berlin tomorrow. Always fetch a 2-day weather forecast for Berlin, select the tomorrow value, and then recommend an outfit. Do NOT answer without calling get_weather_forecast first.',
+      },
+    },
+    {
+      user: 'Do I need an umbrella in Paris today?',
+      tool: 'get_current_weather',
+      args: { city: 'Paris' },
+    },
+    {
+      user: 'Is it cold in San Francisco this weekend?',
+      tool: 'get_weather_forecast',
+      args: { city: 'San Francisco', days: 3 },
+    },
+  ],
+  tags: [
+    'weather',
+    'forecast',
+    'outfit',
+    'travel',
+    'temperature',
+    'rain',
+    'umbrella',
+    'jacket',
+    'clothing',
+    'recommendation',
+  ],
+  category: 'data',
+  visibility: 'on-demand',
+  stability: 'experimental',
+};
+
+interface WeatherNowResponse {
+  ok: boolean;
+  city?: string;
+  temp_c?: number;
+  units?: Units;
+  conditions?: string;
+  latitude?: number;
+  longitude?: number;
+  error?: string;
+}
+
+/**
+ * Weather plugin — exercises every documented `OraclePlugin` hook:
+ *  • `getTools`                 → `get_current_weather` (boot-time, uses config)
+ *  • `getRequestTools`          → `get_weather_forecast` (reads `rtCtx.user.timezone`)
+ *  • `getSubAgents`             → Weather Planner Agent (forecast → outfit chain)
+ *  • `getMiddlewares`           → logs before/after every model call w/ elapsed ms
+ *  • `getRoutes`                → `GET /weather/now?city=X` (Open-Meteo via fetch)
+ *  • `getAuthExcludedRoutes`    → opts `/weather/now` out of UCAN auth
+ *  • `getSharedState`           → `lastWeatherQuery` accessor for other plugins
+ *  • `configSchema`             → optional `WEATHER_DEFAULT_UNITS` (celsius|fahrenheit)
+ *  • `autoDetect`               → always-on (no env gate)
+ *  • `manifest.visibility`      → `on-demand` so `load_capability` is testable
+ *
+ * Port of `apps/qiforge-example/src/plugins/weather` — identical except the
+ * NestJS controller became a `getRoutes()` entry.
+ */
+export class WeatherPlugin extends OraclePlugin {
+  static readonly NAME = NAME;
+
+  readonly name = NAME;
+
+  readonly version = VERSION;
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  override readonly autoDetectHint =
+    'always on (set WEATHER_DEFAULT_UNITS to celsius|fahrenheit)';
+
+  /** Most recent query per session — written by tools, read via `getSharedState`. */
+  private readonly lastBySession: LastQueryStore = new Map<
+    string,
+    LastWeatherQuery
+  >();
+
+  override autoDetect(): boolean {
+    return true;
+  }
+
+  private units(config: unknown): Units {
+    return configSchema.parse(config).WEATHER_DEFAULT_UNITS;
+  }
+
+  override getTools(ctx: PluginContext): PluginTool[] {
+    return [
+      buildCurrentWeatherTool(this.units(ctx.config), this.lastBySession),
+    ];
+  }
+
+  override getRequestTools(rtCtx: RuntimeContext): PluginTool[] {
+    return [buildForecastTool(this.units(rtCtx.config), this.lastBySession)];
+  }
+
+  override getSubAgents(ctx: PluginContext): PluginSubAgent[] {
+    return [
+      buildWeatherPlannerSubAgent(this.units(ctx.config), this.lastBySession),
+    ];
+  }
+
+  override getMiddlewares(ctx: PluginContext): AgentMiddleware[] {
+    return [buildWeatherMiddleware(ctx)];
+  }
+
+  override getRoutes(ctx: PluginContext): PluginRoute[] {
+    const units = this.units(ctx.config);
+    return [
+      {
+        method: 'GET',
+        path: '/weather/now',
+        handler: async (request) => {
+          const city = new URL(request.url).searchParams.get('city');
+          const body = await weatherNow(city, units);
+          return Response.json(body, { status: body.ok ? 200 : 400 });
+        },
+      },
+    ];
+  }
+
+  override getAuthExcludedRoutes(): AuthExcludedRoute[] {
+    // `/weather/now` is a public lookup — Open-Meteo doesn't need user auth.
+    return [{ path: 'weather/now', method: 'GET' }];
+  }
+
+  override getSharedState(): Record<
+    string,
+    (state: unknown, runCtx: RuntimeContext) => unknown
+  > {
+    return {
+      lastWeatherQuery: (_state, runCtx) =>
+        this.lastBySession.get(runCtx.session.id),
+    };
+  }
+}
+
+/** `GET /weather/now?city=X` body — same shape as the Node controller's. */
+export async function weatherNow(
+  city: string | null,
+  units: Units,
+): Promise<WeatherNowResponse> {
+  if (!city || city.trim().length === 0) {
+    return { ok: false, error: 'Missing required query param: city' };
+  }
+  try {
+    const result = await getCurrentWeather(city, units);
+    if (!result) {
+      return { ok: false, error: `Could not find weather for "${city}".` };
+    }
+    return {
+      ok: true,
+      city: result.city,
+      temp_c: result.temp,
+      units: result.units,
+      conditions: result.conditions,
+      latitude: result.latitude,
+      longitude: result.longitude,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : 'Weather lookup failed.',
+    };
+  }
+}