Apps & transmissions

import { defineTransmissionEvent } from "glove-foundry";

export default defineTransmissionEvent({
  direction: "inbound",
  description: "A customer opened a help-desk ticket.",
});

import { defineTransmissionEvent } from "glove-foundry";

export default defineTransmissionEvent({
  direction: "outbound",
  description: "The agent posted a public reply on the ticket.",
});

import { Effect } from "effect";
import { defineTransmissionPredicate } from "glove-foundry";

/** Priority runs 1 (low) to 4 (urgent). Playbooks pass the threshold as a parameter. */
export default defineTransmissionPredicate({
  description: "The ticket's priority is at least parameters.minimum (default 3).",
  match: (event: { readonly priority: number }, parameters) =>
    Effect.succeed(event.priority >= Number(parameters.minimum ?? 3)),
});

import { Effect, Schema } from "effect";
import { defineTransmission } from "glove-foundry";
import ticketCreated from "../events/ticket-created.event.js";
import ticketReplied from "../events/ticket-replied.event.js";
import priorityAtLeast from "../predicates/priority-at-least.predicate.js";

/** Declared authority. A binding can only grant capabilities listed here. */
export const replyToTicket = {
  id: "tickets:reply",
  description: "Post a public reply on a ticket",
  account: "required",
  effect: "write",
} as const;

/** The provider's webhook body, exactly as the help desk sends it. */
export const HelpdeskWebhook = Schema.Struct({
  event_id: Schema.String,
  queue: Schema.String,
  ticket: Schema.Struct({
    id: Schema.String,
    subject: Schema.String,
    description: Schema.String,
    priority: Schema.Literal("low", "normal", "high", "urgent"),
    requester_email: Schema.String,
  }),
});

const PRIORITY = { low: 1, normal: 2, high: 3, urgent: 4 } as const;

// your code: the provider SDK. This fake keeps the sample runnable.
const helpdeskApi = {
  async reply(_token: string, ticketId: string, _body: string, _signal: AbortSignal) {
    return { commentId: `comment_${ticketId}_${Date.now()}` };
  },
};

export default defineTransmission({
  name: "Tickets",
  description: "Help-desk tickets in, public ticket replies out",
  account: {
    required: true,
    metadata: Schema.Struct({ subdomain: Schema.String }),
  },
  capabilities: [replyToTicket],
  events: [ticketCreated, ticketReplied],
  inbound: {
    config: Schema.Struct({ queue: Schema.String }),
    // The normalized event that predicates, playbooks and the agent see.
    event: Schema.Struct({
      ticketId: Schema.String,
      subject: Schema.String,
      body: Schema.String,
      priority: Schema.Number,
      requester: Schema.String,
    }),
    adapter: {
      // Refuse events for a queue this route does not serve.
      authenticate: (raw, { route }) =>
        Schema.decodeUnknown(HelpdeskWebhook)(raw).pipe(
          Effect.map((hook) => hook.queue === route.config.queue),
          Effect.orElseSucceed(() => false),
        ),
      // Provider shape in, your event shape out.
      normalize: (raw) =>
        Schema.decodeUnknown(HelpdeskWebhook)(raw).pipe(
          Effect.map(({ ticket }) => ({
            ticketId: ticket.id,
            subject: ticket.subject,
            body: ticket.description,
            priority: PRIORITY[ticket.priority],
            requester: ticket.requester_email,
          })),
          Effect.orDie,
        ),
    },
    classify: () => Effect.succeed(ticketCreated),
    predicates: [priorityAtLeast],
  },
  outbound: {
    config: Schema.Struct({ queue: Schema.String }),
    input: Schema.Struct({ ticketId: Schema.String, body: Schema.String }),
    output: Schema.Struct({ commentId: Schema.String }),
    // Long replies wait for a human approval before delivery.
    requiresPermission: (input: { readonly body: string }) => input.body.length > 1_500,
    // Secret-safe trace data. Without observe, the payload is not retained at all.
    observe: (input: { readonly ticketId: string; readonly body: string }) => ({
      ticketId: input.ticketId,
      characters: input.body.length,
    }),
    adapter: {
      deliver: (input: { readonly ticketId: string; readonly body: string }, context) =>
        context.withAccountSession
          ? context
              .withAccountSession("tickets:reply", (session) =>
                Effect.tryPromise(() =>
                  helpdeskApi.reply(
                    (session as { readonly token: string }).token,
                    input.ticketId,
                    input.body,
                    context.signal,
                  ),
                ),
              )
              .pipe(Effect.orDie)
          : Effect.die(new Error("Add accountSessions to the agent to reply on tickets.")),
    },
  },
});

import { Effect } from "effect";
import { defineApp } from "glove-foundry";
import { z } from "zod";
import ticketsPoller from "../connections/tickets-poller.connection.js";
import tickets from "../transmissions/tickets.transmission.js";

const helpdesk = defineApp({
  description: "Receive help-desk tickets and reply on them",
  config: z.object({ queue: z.string().default("support") }),
  inbound: [tickets], // tickets can start runs on instances that install this app
  outbound: [tickets], // mounted as the tool glove_app_helpdesk__tickets_send
  connections: [ticketsPoller], // optional; omit it when tickets arrive by webhook
  install: ({ config, accountId }) =>
    Effect.succeed({
      tools: [
        {
          name: "helpdesk_queue",
          description: "Report which help-desk queue and account this agent serves",
          inputSchema: z.object({}),
          async do() {
            return { status: "success" as const, data: { queue: config.queue, accountId } };
          },
        },
      ],
    }),
});

export default helpdesk;

import { defineAccount, defineInboundRoute, defineOutboundRoute } from "glove-foundry";
import tickets from "./transmissions/tickets.transmission.js";

export const acmeHelpdesk = defineAccount({
  id: "acme-helpdesk",
  transmission: tickets,
  externalAccountId: "acme", // the provider's id for this account
  label: "Acme help desk",
  accessRef: "vault://helpdesk/acme", // opaque: only your accountSessions adapter reads it
  metadata: { subdomain: "acme" }, // checked against tickets.account.metadata
});

export const ticketsInbound = defineInboundRoute({
  id: "tickets-inbound",
  transmission: tickets,
  account: acmeHelpdesk,
  visibility: "workspace",
  enabled: true,
  config: { queue: "support" }, // checked against tickets.inbound.config
});

export const ticketsOutbound = defineOutboundRoute({
  id: "tickets-outbound",
  transmission: tickets,
  account: acmeHelpdesk,
  visibility: "workspace",
  enabled: true,
  config: { queue: "support" }, // checked against tickets.outbound.config
});

import { defineAgentInstance, install } from "glove-foundry";
import support from "./agent.js";
import helpdesk from "./apps/helpdesk.app.js";
import { acmeHelpdesk } from "./topology.js";

export const supportDesk = defineAgentInstance(support, {
  id: "support-desk",
  workspaceId: "acme",
  installations: [install(helpdesk, { queue: "support" }, { account: acmeHelpdesk })],
});

import { MemoryFoundryDataAdapter, defineApplication, defineBinding } from "glove-foundry";
import helpdesk from "./agents/support/apps/helpdesk.app.js";
import { supportDesk } from "./agents/support/instances.js";
import { acmeHelpdesk, ticketsInbound, ticketsOutbound } from "./agents/support/topology.js";
import tickets, { replyToTicket } from "./agents/support/transmissions/tickets.transmission.js";

// Outbound delivery is authorized per instance: this grants support-desk the reply route.
const supportDeskReplies = defineBinding({
  id: "support-desk-replies",
  agent: supportDesk,
  application: helpdesk,
  transmission: tickets,
  account: acmeHelpdesk,
  route: ticketsOutbound,
  capabilities: [replyToTicket],
  enabled: true,
});

export default defineApplication({
  name: "Acme Support",
  data: new MemoryFoundryDataAdapter({ agents: [supportDesk] }),
  accounts: [acmeHelpdesk],
  routes: [ticketsInbound, ticketsOutbound],
  bindings: [supportDeskReplies],
});

import { Effect } from "effect";
import { createAdapter } from "glove-core/models/providers";
import { composeAgent, composePlaybook, defineAgent } from "glove-foundry";
import triage from "./actions/triage.action.js";
import helpdesk from "./apps/helpdesk.app.js";
import ticketCreated from "./events/ticket-created.event.js";
import ticketReplied from "./events/ticket-replied.event.js";
import priorityAtLeast from "./predicates/priority-at-least.predicate.js";
import { acmeHelpdesk, ticketsInbound, ticketsOutbound } from "./topology.js";
import tickets from "./transmissions/tickets.transmission.js";

// your code: resolve the credential behind an account. Foundry never sees it.
async function helpdeskToken(_accountId: string): Promise<string> {
  return process.env.HELPDESK_API_TOKEN ?? "dev-token";
}

const urgentTickets = composePlaybook({
  name: "urgent-tickets",
  transmission: tickets,
  match: {
    event: ticketCreated,
    routes: [ticketsInbound],
    predicate: { definition: priorityAtLeast, parameters: { minimum: 3 } },
  },
  directives: [{ action: triage, instruction: "Work out what the customer needs, then reply on the ticket." }],
  applications: [helpdesk],
  outbound: [{
    route: ticketsOutbound,
    application: helpdesk,
    account: acmeHelpdesk,
    event: ticketReplied,
    instruction: "Reply on the same ticket.",
  }],
});

export default defineAgent({
  description: "Answers help-desk tickets",
  components: composeAgent(helpdesk), // available, not yet mounted
  model: () => createAdapter({ provider: "openrouter", model: "openai/gpt-4.1-mini", stream: true }),
  systemPrompt: "You are Acme's support agent. Be brief and specific.",

  // The credential boundary. Foundry passes an accountId and an operation name.
  accountSessions: {
    identifier: "helpdesk-tokens",
    withSession: (request, use) =>
      Effect.promise(() => helpdeskToken(request.accountId)).pipe(
        Effect.flatMap((token) => use({ token })),
      ),
  },

  // A playbook is only valid on an instance that installed helpdesk.
  playbooks: (_agent, { installations }) =>
    installations.some((item) => item.kind === "application" && item.id === helpdesk.id)
      ? [urgentTickets]
      : [],
});

<transmission direction="inbound" definition="tickets" route="tickets-inbound" event="ticket-created" event-id="evt_1001" thread="T-1001">
  <payload format="json">{&quot;body&quot;:&quot;Where is order 4417?&quot;,&quot;priority&quot;:4,&quot;requester&quot;:&quot;dana@example.com&quot;,&quot;subject&quot;:&quot;Order never arrived&quot;,&quot;ticketId&quot;:&quot;T-1001&quot;}</payload>
  <playbook id="playbook-3f9c…">
      <directive action="triage">
        <instruction>Work out what the customer needs, then reply on the ticket.</instruction>
      </directive>
      <outbound route="tickets-outbound" application="helpdesk" event="ticket-replied" account="acme-helpdesk">Reply on the same ticket.</outbound>
  </playbook>
</transmission>

curl -X POST http://127.0.0.1:4141/api/transmissions/tickets-inbound/fire \
  -H 'content-type: application/json' \
  -d '{
    "eventId": "evt_1001",
    "threadKey": "T-1001",
    "raw": {
      "event_id": "evt_1001",
      "queue": "support",
      "ticket": { "id": "T-1001", "subject": "Order never arrived",
        "description": "Where is order 4417?", "priority": "urgent",
        "requester_email": "dana@example.com" }
    }
  }'
# 202 Accepted -> the started runs, [] when no playbook matched:
# [{ "id": "…", "agent": "support", "status": "pending", "agentId": "support-desk",
#    "conversationId": "transmission:tickets-inbound:support-desk:T-1001", … }]

import { createHmac, timingSafeEqual } from "node:crypto";
import { createFoundryClient } from "glove-foundry/client";

const foundry = createFoundryClient({
  baseUrl: process.env.FOUNDRY_URL ?? "http://127.0.0.1:4141",
  // Only needed when foundry.application.ts sets requestAuthorization.
  authorization: {
    identifier: "helpdesk-webhook",
    headers: () => ({ authorization: `Bearer ${process.env.FOUNDRY_API_TOKEN ?? ""}` }),
  },
});

export async function POST(request: Request): Promise<Response> {
  const body = await request.text();
  const expected = createHmac("sha256", process.env.HELPDESK_WEBHOOK_SECRET ?? "")
    .update(body)
    .digest("hex");
  const signature = request.headers.get("x-helpdesk-signature") ?? "";
  if (
    signature.length !== expected.length ||
    !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return new Response("invalid signature", { status: 401 });
  }

  const hook = JSON.parse(body) as { event_id: string; ticket: { id: string } };
  const runs = await foundry.dispatchInbound({
    routeId: "tickets-inbound",
    eventId: hook.event_id, // a provider retry reuses it, so nothing runs twice
    threadKey: hook.ticket.id, // one conversation per ticket
    raw: hook, // goes through tickets.inbound.adapter
  });
  return Response.json({ runIds: runs.map((run) => run.id) }, { status: 202 });
}

import { Effect } from "effect";
import { defineConnection } from "glove-foundry";
import tickets, { HelpdeskWebhook } from "../transmissions/tickets.transmission.js";

// your code: ask the help desk for tickets created since the last poll.
async function fetchNewTickets(
  _queue: string,
  _signal: AbortSignal,
): Promise<ReadonlyArray<typeof HelpdeskWebhook.Type>> {
  return [];
}

export default defineConnection({
  description: "Polls the help desk for new tickets every 30 seconds",
  transmissions: [tickets],
  connect: (ctx) =>
    Effect.gen(function* () {
      yield* ctx.ready(); // the inspector now shows this connection as "connected"
      while (!ctx.signal.aborted) {
        for (const route of ctx.routes) {
          const batch = yield* Effect.tryPromise(() =>
            fetchNewTickets(String(route.config.queue), ctx.signal),
          );
          for (const hook of batch) {
            yield* ctx.receive({
              route,
              eventId: hook.event_id, // dedupe key: "<routeId>:<eventId>"
              threadKey: hook.ticket.id, // one conversation per ticket
              raw: hook,
            });
          }
        }
        yield* Effect.sleep("30 seconds");
      }
    }),
});

glove_app_<app id>__<transmission id>_send      ("/" becomes "__", "-" becomes "_")

helpdesk + tickets              -> glove_app_helpdesk__tickets_send
support-desk + email/replies    -> glove_app_support_desk__email__replies_send