glove-foundry 0.0.0 → 0.2.0

package/templates/travel-concierge/agents/concierge/apps/calendar.app.ts

@@ -0,0 +1,67 @@
+import { Effect } from "effect";
+import { defineApp } from "glove-foundry";
+import { z } from "zod";
+import messaging from "../transmissions/messaging.transmission.js";
+
+/**
+ * An application is a capability an *instance* installs, not something the
+ * definition always has. Two concierge instances can run the same code with
+ * different calendars, or with none at all.
+ *
+ * `config` is validated when the instance installs it, so `install` receives a
+ * typed value. Swap the in-memory `HELD` map for a real calendar API.
+ */
+const HELD = new Map<string, { readonly start: string; readonly end: string }>();
+
+const calendar = defineApp({
+  description: "Read a traveller's calendar and hold provisional trip dates",
+  config: z.object({
+    calendarId: z.string().default("primary"),
+    timezone: z.string().default("UTC"),
+  }),
+  // Declaring the transmission here lets an installed instance send messages.
+  inbound: [messaging],
+  outbound: [messaging],
+  install: ({ config }) => Effect.succeed({
+    tools: [
+      {
+        name: "calendar_check_availability",
+        description: "Check whether a date range is free on the traveller's calendar",
+        inputSchema: z.object({
+          start: z.string().describe("ISO start date, for example 2026-04-02"),
+          end: z.string().describe("ISO end date, for example 2026-04-09"),
+        }),
+        async do({ start, end }) {
+          const clash = [...HELD.values()].find((hold) => hold.start <= end && start <= hold.end);
+          return {
+            status: "success" as const,
+            data: {
+              calendarId: config.calendarId,
+              timezone: config.timezone,
+              available: !clash,
+              ...(clash ? { conflictsWith: clash } : {}),
+            },
+          };
+        },
+      },
+      {
+        name: "calendar_hold_dates",
+        description: "Place a provisional hold on a date range while the trip is being planned",
+        inputSchema: z.object({
+          label: z.string().describe("What the hold is for, for example 'Nairobi trip'"),
+          start: z.string(),
+          end: z.string(),
+        }),
+        async do({ label, start, end }) {
+          HELD.set(label, { start, end });
+          return {
+            status: "success" as const,
+            data: { held: true, label, start, end, calendarId: config.calendarId },
+          };
+        },
+      },
+    ],
+  }),
+});
+
+export default calendar;

package/templates/travel-concierge/agents/concierge/composition.ts

@@ -0,0 +1,18 @@
+import { composeAgent } from "glove-foundry";
+import calendar from "./apps/calendar.app.js";
+import tripContext from "./layers/trip-context.layer.js";
+import travellerMemory from "./memory/traveller.memory.js";
+import usage from "./subscribers/usage.subscriber.js";
+import findFlights from "./tools/find-flights.tool.js";
+
+/**
+ * Composition is by value, not by string id. Rename a file and the import
+ * breaks at compile time instead of failing at runtime.
+ */
+export const conciergeComponents = composeAgent(
+  calendar,
+  findFlights,
+  travellerMemory,
+  tripContext,
+  usage,
+);

package/templates/travel-concierge/agents/concierge/events/message-received.event.ts

@@ -0,0 +1,7 @@
+import { defineTransmissionEvent } from "glove-foundry";
+
+/** A traveller sent the concierge a message from a chat app. */
+export default defineTransmissionEvent({
+  direction: "inbound",
+  description: "A traveller message arrived from a chat transport.",
+});

package/templates/travel-concierge/agents/concierge/events/message-sent.event.ts

@@ -0,0 +1,7 @@
+import { defineTransmissionEvent } from "glove-foundry";
+
+/** The concierge replied into the same chat thread. */
+export default defineTransmissionEvent({
+  direction: "outbound",
+  description: "A concierge reply was delivered back to the traveller.",
+});

package/templates/travel-concierge/agents/concierge/layers/trip-context.layer.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { defineLayer } from "glove-foundry";
+
+/**
+ * A layer reaches the native Glove runtime directly. Use it when you need
+ * something a tool cannot express — here, a skill the model can read without
+ * spending a tool call.
+ */
+const tripContext = defineLayer({
+  description: "Expose the current Foundry run identity to the agent",
+  setup: ({ glove, agentId, runId, history }) => Effect.sync(() => {
+    glove.defineSkill({
+      name: "trip-context",
+      description: "Where this conversation stands",
+      exposeToAgent: true,
+      async handler() {
+        return `agent=${agentId} run=${runId} priorMessages=${history.length}`;
+      },
+    });
+  }),
+});
+
+export default tripContext;

package/templates/travel-concierge/agents/concierge/memory/traveller.memory.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import { defineMemory } from "glove-foundry";
+import { MemorySchema } from "glove-memory/core";
+import { InMemoryContextAdapter } from "glove-memory/in-memory";
+
+/**
+ * Ambient context the concierge should carry between conversations: seat
+ * preference, home airport, who is travelling. The adapter is replaceable —
+ * point it at a durable store when you outgrow the in-memory one.
+ */
+const schema = new MemorySchema();
+const context = new InMemoryContextAdapter({ schema });
+
+const travellerMemory = defineMemory({
+  description: "What we already know about this traveller",
+  context: { adapter: () => Effect.succeed(context) },
+});
+
+export default travellerMemory;

package/templates/travel-concierge/agents/concierge/predicates/mentions-trip.predicate.ts

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { defineTransmissionPredicate } from "glove-foundry";
+
+/**
+ * Predicates keep routing decisions out of the agent. A playbook references
+ * this by value and supplies `parameters` at match time, so one predicate
+ * serves many rules.
+ */
+const mentionsTrip = defineTransmissionPredicate({
+  match: (event: { readonly text: string }, parameters) => {
+    const needles = Array.isArray(parameters.any) ? parameters.any : ["trip", "flight", "travel"];
+    const text = event.text.toLowerCase();
+    return Effect.succeed(needles.some((needle) => text.includes(String(needle).toLowerCase())));
+  },
+});
+
+export default mentionsTrip;

package/templates/travel-concierge/agents/concierge/schedules/trip-countdown.ts

@@ -0,0 +1,16 @@
+import { defineSchedule } from "glove-foundry";
+
+/**
+ * Agents never call setTimeout. A schedule is a definition; Foundry persists
+ * the activation and wakes the agent with this message. Watch it appear under
+ * Automations in the inspector.
+ */
+const tripCountdown = defineSchedule({
+  name: "trip-countdown",
+  description: "Check every weekday whether an upcoming trip still needs work.",
+  timing: { kind: "cron", expression: "0 8 * * 1-5", timezone: "UTC" },
+  message:
+    "Review any held trip dates and unconfirmed bookings. If something needs the traveller's decision, say exactly what and why.",
+});
+
+export default tripCountdown;

package/templates/travel-concierge/agents/concierge/subscribers/usage.subscriber.ts

@@ -0,0 +1,16 @@
+import { defineSubscriber } from "glove-foundry";
+
+/**
+ * Subscribers observe without changing behaviour. Everything they see is also
+ * in the inspector's event trace; this is the seam for shipping it elsewhere.
+ */
+const usage = defineSubscriber({
+  description: "Report token consumption for each run",
+  create: {
+    async record(type, data) {
+      if (type === "token_consumption") process.stdout.write(`[tokens] ${JSON.stringify(data)}\n`);
+    },
+  },
+});
+
+export default usage;

package/templates/travel-concierge/agents/concierge/tools/find-flights.tool.ts

@@ -0,0 +1,49 @@
+import { defineSharedTool } from "glove-foundry";
+import { z } from "zod";
+
+/**
+ * A shared tool is the smallest Foundry capability: one file, one default
+ * export, and an id taken from the filename (`find-flights`). Nothing here
+ * knows which agent will mount it.
+ *
+ * The sample data is deliberately local so a fresh project runs offline.
+ * Replace `search` with a call to your own inventory or a provider API.
+ */
+const SAMPLE_FLIGHTS = [
+  { carrier: "Kestrel Air", from: "LIS", to: "NBO", depart: "08:40", hours: 9.5, price: 612 },
+  { carrier: "Meridian", from: "LIS", to: "NBO", depart: "13:15", hours: 11, price: 494 },
+  { carrier: "Northwind", from: "LIS", to: "NBO", depart: "22:05", hours: 9, price: 738 },
+] as const;
+
+function search(from: string, to: string, maxPrice: number) {
+  const origin = from.trim().toUpperCase();
+  const destination = to.trim().toUpperCase();
+  return SAMPLE_FLIGHTS.filter((flight) =>
+    (!origin || flight.from === origin) &&
+    (!destination || flight.to === destination) &&
+    flight.price <= maxPrice
+  );
+}
+
+const findFlights = defineSharedTool({
+  description: "Search available flights between two airports",
+  tool: {
+    name: "find_flights",
+    description:
+      "Search flights between two IATA airport codes. Returns carrier, departure time, duration and price.",
+    inputSchema: z.object({
+      from: z.string().describe("Origin IATA code, for example LIS"),
+      to: z.string().describe("Destination IATA code, for example NBO"),
+      maxPrice: z.number().default(5_000).describe("Highest acceptable price in USD"),
+    }),
+    async do({ from, to, maxPrice }) {
+      const matches = search(from, to, maxPrice);
+      if (matches.length === 0) {
+        return { status: "success" as const, data: { matches: [], note: "No flight matched those constraints." } };
+      }
+      return { status: "success" as const, data: { matches } };
+    },
+  },
+});
+
+export default findFlights;

package/templates/travel-concierge/agents/concierge/topology.ts

@@ -0,0 +1,35 @@
+import { defineAccount, defineInboundRoute, defineOutboundRoute } from "glove-foundry";
+import messaging from "./transmissions/messaging.transmission.js";
+
+/**
+ * Topology is runtime *data*, not code identity — which is why these carry
+ * explicit ids. Edit them, load them from your database, or create them from
+ * the inspector; the agent definition above does not change.
+ */
+export const travellerAccount = defineAccount({
+  id: "traveller-chat",
+  transmission: messaging,
+  externalAccountId: "demo-traveller",
+  label: "Demo traveller chat",
+  // The real credential stays behind this reference, inside an adapter you own.
+  accessRef: "adapter://messaging/demo-traveller",
+  metadata: { handle: "@demo_traveller", provider: "telegram" },
+});
+
+export const travellerInbound = defineInboundRoute({
+  id: "traveller-inbound",
+  transmission: messaging,
+  account: travellerAccount,
+  visibility: "private",
+  enabled: true,
+  config: { provider: "telegram" },
+});
+
+export const travellerOutbound = defineOutboundRoute({
+  id: "traveller-outbound",
+  transmission: messaging,
+  account: travellerAccount,
+  visibility: "private",
+  enabled: true,
+  config: { provider: "telegram" },
+});

package/templates/travel-concierge/agents/concierge/transmissions/messaging.transmission.ts

@@ -0,0 +1,57 @@
+import { Effect, Schema } from "effect";
+import { defineTransmission } from "glove-foundry";
+import mentionsTrip from "../predicates/mentions-trip.predicate.js";
+import messageReceived from "../events/message-received.event.js";
+import messageSent from "../events/message-sent.event.js";
+
+/**
+ * A transmission is the *shape* of an external transport, not a vendor SDK.
+ * Telegram and WhatsApp both look like "a chat with threads", so one
+ * transmission covers both and `config.provider` picks which.
+ *
+ * Foundry never stores credentials. `account.metadata` holds safe descriptive
+ * fields; the secret itself lives behind `accessRef` in an adapter you own.
+ */
+export const sendMessage = {
+  id: "messaging:send",
+  description: "Send a message into a traveller's chat thread",
+  account: "required",
+  effect: "write",
+} as const;
+
+/** Swap this for a real Bot API call. See README, "Connecting a real chat app". */
+function deliver(input: { readonly threadId: string; readonly text: string }, provider: string) {
+  process.stdout.write(`[${provider}] -> ${input.threadId}: ${input.text}\n`);
+  return Effect.succeed({ externalMessageId: `${provider}:${input.threadId}:${Date.now()}` });
+}
+
+const messaging = defineTransmission({
+  name: "Messaging",
+  description: "Chat transport for Telegram, WhatsApp, or any threaded messenger",
+  account: {
+    required: true,
+    metadata: Schema.Struct({
+      handle: Schema.String,
+      provider: Schema.Literal("telegram", "whatsapp"),
+    }),
+  },
+  capabilities: [sendMessage],
+  events: [messageReceived, messageSent],
+  inbound: {
+    config: Schema.Struct({ provider: Schema.Literal("telegram", "whatsapp") }),
+    event: Schema.Struct({ threadId: Schema.String, text: Schema.String }),
+    classify: () => Effect.succeed(messageReceived),
+    predicates: [mentionsTrip],
+  },
+  outbound: {
+    config: Schema.Struct({ provider: Schema.Literal("telegram", "whatsapp") }),
+    input: Schema.Struct({ threadId: Schema.String, text: Schema.String }),
+    output: Schema.Struct({ externalMessageId: Schema.String }),
+    adapter: {
+      deliver: (input, context) =>
+        deliver(input, (context.route.config as { provider?: string }).provider ?? "telegram"),
+    },
+  },
+});
+
+export default messaging;

package/templates/travel-concierge/agents/concierge/workbench.ts

@@ -0,0 +1,26 @@
+import { JsSession, defineFn } from "glove-js";
+import { defineRepl, defineWorkingEnvironment } from "glove-foundry";
+import { z } from "zod";
+
+/**
+ * The workbench is the agent's own sandbox: a virtual filesystem for building
+ * up an itinerary document, and a JavaScript REPL for arithmetic the model
+ * should not do in its head (totals, date maths, currency).
+ *
+ * Delete either one if this agent does not need it.
+ */
+export const conciergeWorkspace = defineWorkingEnvironment({
+  options: { limits: { maxVfsBytes: 16 * 1024 * 1024 } },
+});
+
+export function conciergeRepl(actor: string, budgetUsd: number) {
+  const session = JsSession.create({ actor });
+  session.register(defineFn({
+    name: "trip__budget",
+    description: "Read the traveller's remaining budget in USD",
+    input: z.object({}),
+    readOnlyHint: true,
+    handler: () => ({ budgetUsd }),
+  }));
+  return defineRepl({ language: "javascript", session });
+}

package/templates/travel-concierge/env.example

@@ -0,0 +1,3 @@
+# Leave these empty to use the built-in demo model. Set them for real answers.
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=openai/gpt-4.1-mini

package/templates/travel-concierge/foundry.application.ts

@@ -0,0 +1,18 @@
+import { MemoryFoundryDataAdapter, defineApplication } from "glove-foundry";
+import { travellerAccount, travellerInbound, travellerOutbound } from "./agents/concierge/topology.js";
+
+/**
+ * The application is where runtime data enters: which adapter persists
+ * instances, which accounts and routes exist. `MemoryFoundryDataAdapter` keeps
+ * everything in process, so restarting `pnpm dev` starts clean. Swap it for
+ * your own adapter to persist across restarts.
+ */
+export const data = new MemoryFoundryDataAdapter();
+
+export default defineApplication({
+  name: "{{projectName}}",
+  data,
+  accounts: [travellerAccount],
+  routes: [travellerInbound, travellerOutbound],
+  bindings: [],
+});

package/templates/travel-concierge/foundry.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "glove-foundry/config";
+
+export default defineConfig({
+  server: { port: 4141 },
+  execution: {
+    pollIntervalMs: 100,
+    maxConcurrent: 4,
+  },
+});

package/templates/travel-concierge/gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env.local
+.foundry/manifest.json

package/templates/travel-concierge/lib/demo-model.ts

@@ -0,0 +1,72 @@
+import type {
+  Message,
+  ModelAdapter,
+  ModelPromptResult,
+  NotifySubscribersFunction,
+  PromptRequest,
+  ToolCall,
+} from "glove-core";
+
+/**
+ * A deterministic stand-in used when OPENROUTER_API_KEY is absent, so a fresh
+ * project runs end to end — real runs, real tool calls, a real event trace in
+ * the inspector — before you have configured a provider.
+ *
+ * Delete this file and the `model()` fallback in agent.ts once you have a key.
+ */
+export class DemoModel implements ModelAdapter {
+  readonly name = "demo-model";
+  private systemPrompt = "";
+
+  setSystemPrompt(prompt: string): void {
+    this.systemPrompt = prompt;
+  }
+
+  async prompt(
+    request: PromptRequest,
+    notify: NotifySubscribersFunction,
+  ): Promise<ModelPromptResult> {
+    const toolCompleted = request.messages.some(
+      (message) => Array.isArray(message.tool_results) && message.tool_results.length > 0,
+    );
+
+    if (!toolCompleted) {
+      // First turn: call a real tool so the trace shows tool_use -> result.
+      // ToolCall's fields are optional, so notify() reads the local literals.
+      const callId = "call_demo_flights";
+      const toolName = "find_flights";
+      const input = { from: "LIS", to: "NBO", maxPrice: 5_000 };
+      const call: ToolCall = { id: callId, tool_name: toolName, input_args: input };
+      await notify("tool_use", { id: callId, name: toolName, input });
+      await notify("model_response_complete", {
+        text: "",
+        tool_calls: [call],
+        stop_reason: "tool_use",
+        tokens_in: 14,
+        tokens_out: 6,
+      });
+      const message: Message = { sender: "agent", text: "", tool_calls: [call] };
+      return { messages: [message], tokens_in: 14, tokens_out: 6 };
+    }
+
+    const asked = [...request.messages]
+      .reverse()
+      .find((message) => message.sender === "user" && !message.tool_results?.length)?.text;
+    const text = [
+      `Here is what I found for "${asked ?? "your trip"}".`,
+      "Three flights match. Meridian at 13:15 is the cheapest at $494; Northwind at 22:05 is the fastest at 9h.",
+      "Tell me your dates and I will check the calendar and hold them.",
+      "",
+      "(This is the built-in demo model. Set OPENROUTER_API_KEY in .env.local for real answers.)",
+    ].join("\n");
+    await notify("text_delta", { text });
+    await notify("model_response_complete", {
+      text,
+      stop_reason: "end_turn",
+      tokens_in: 32,
+      tokens_out: 48,
+    });
+    void this.systemPrompt;
+    return { messages: [{ sender: "agent", text }], tokens_in: 32, tokens_out: 48 };
+  }
+}

package/templates/travel-concierge/src/client.ts

@@ -0,0 +1,22 @@
+/**
+ * A typed client for this project's agents. `FoundryRoutes` is generated into
+ * .foundry/routes.d.ts on every `glove foundry dev`, so `agent("concierge")`
+ * is checked against the files that actually exist.
+ *
+ * Run with: npx tsx src/client.ts (while `pnpm dev` is running)
+ */
+import { createFoundryClient } from "glove-foundry/client";
+import type { FoundryRoutes } from "../.foundry/routes.js";
+
+const foundry = createFoundryClient<FoundryRoutes>({ baseUrl: "http://127.0.0.1:4141" });
+
+const agent = await foundry.agent("concierge").create({
+  workspaceId: "demo",
+  context: { budgetUsd: 2_500 },
+});
+const conversation = await foundry.createConversation(agent.id);
+const run = await foundry.send(agent.id, conversation.id, "I want to fly from Lisbon to Nairobi in April.");
+
+console.log(`run ${run.id} -> http://127.0.0.1:4141/runs/${run.id}`);
+const completed = await run.wait();
+console.log(completed.output);