@on-mission/sdk 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+/**
+ * API Client
+ *
+ * Typed tRPC client for all SDK -> Mission gateway communication.
+ * The public SDK surface stays the same (`mission.auth.get()`, etc.),
+ * while transport details are centralized here.
+ */
+import type { GatewayRouter } from '@mission/api/gateway';
+import { createTRPCProxyClient } from '@trpc/client';
+import type { PluginContext } from './context';
+type GatewayClient = ReturnType<typeof createTRPCProxyClient<GatewayRouter>>;
+export type ApiClient = {
+    trpc: GatewayClient;
+    baseUrl: string;
+    setToken: (token: string) => void;
+    getToken: () => string;
+};
+export declare const createApiClient: (ctx: PluginContext) => ApiClient;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,qBAAqB,EAAiB,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,aAAa,CAAC,CAAC,CAAA;AAE5E,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,aAAa,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,MAAM,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,aAAa,KAAG,SA+BpD,CAAA"}

package/dist/api.js

@@ -0,0 +1,39 @@
+/**
+ * API Client
+ *
+ * Typed tRPC client for all SDK -> Mission gateway communication.
+ * The public SDK surface stays the same (`mission.auth.get()`, etc.),
+ * while transport details are centralized here.
+ */
+import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
+export const createApiClient = (ctx) => {
+    const baseUrl = ctx.apiUrl.replace(/\/$/, '');
+    let currentToken = ctx.pluginToken;
+    const trpc = createTRPCProxyClient({
+        links: [
+            httpBatchLink({
+                url: `${baseUrl}/api/trpc`,
+                headers() {
+                    const headers = {
+                        'X-Mission-Installation-Id': ctx.installationId
+                    };
+                    if (currentToken) {
+                        headers.Authorization = `Bearer ${currentToken}`;
+                    }
+                    return headers;
+                }
+            })
+        ]
+    });
+    return {
+        trpc,
+        baseUrl,
+        setToken: (token) => {
+            currentToken = token;
+        },
+        getToken: () => {
+            return currentToken;
+        }
+    };
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAYnE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAkB,EAAa,EAAE;IAC/D,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC7C,IAAI,YAAY,GAAG,GAAG,CAAC,WAAW,CAAA;IAElC,MAAM,IAAI,GAAG,qBAAqB,CAAgB;QAChD,KAAK,EAAE;YACL,aAAa,CAAC;gBACZ,GAAG,EAAE,GAAG,OAAO,WAAW;gBAC1B,OAAO;oBACL,MAAM,OAAO,GAA2B;wBACtC,2BAA2B,EAAE,GAAG,CAAC,cAAc;qBAChD,CAAA;oBACD,IAAI,YAAY,EAAE,CAAC;wBACjB,OAAO,CAAC,aAAa,GAAG,UAAU,YAAY,EAAE,CAAA;oBAClD,CAAC;oBACD,OAAO,OAAO,CAAA;gBAChB,CAAC;aACF,CAAC;SACH;KACF,CAAC,CAAA;IAEF,OAAO;QACL,IAAI;QACJ,OAAO;QACP,QAAQ,EAAE,CAAC,KAAa,EAAQ,EAAE;YAChC,YAAY,GAAG,KAAK,CAAA;QACtB,CAAC;QACD,QAAQ,EAAE,GAAW,EAAE;YACrB,OAAO,YAAY,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/auth.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Auth Module
+ *
+ * Unified interface for all authentication credentials.
+ * `mission.auth.get()` returns a single object containing:
+ *  - User-provided credentials (API keys, tokens, secrets from the connection form)
+ *  - OAuth token data (for managed auth providers like Google, Slack)
+ *
+ * Plugin authors always call `auth.get()` regardless of auth type.
+ *
+ * For managed auth (Nango-backed), the SDK caches tokens and refreshes
+ * transparently. See docs/technical-designs/managed-auth-nango.md.
+ *
+ * For custom auth, credentials are collected via a connection form
+ * defined in mission.json's `auth.credentials` schema.
+ *
+ * Transport: tRPC mutation/query via Mission gateway API.
+ */
+import type { ApiClient } from './api';
+/**
+ * OAuth credentials returned for managed auth providers.
+ * The control plane handles token refresh (via Nango or equivalent).
+ */
+export type OAuthCredentials = {
+    /** The current access token string. */
+    accessToken: string;
+    /** When this token expires (ISO 8601 or epoch ms). */
+    expiresAt: string | number;
+    /** Scopes that were granted. */
+    scopes: string[];
+    /** The provider identifier (e.g. 'google', 'slack'). */
+    provider: string;
+};
+/**
+ * The unified auth response.
+ *
+ * For custom auth (Sentry, Twilio, etc.):
+ *   { credentials: { authToken: 'sntrys_...', organization: 'my-org' } }
+ *
+ * For managed OAuth (Gmail, Slack, etc.):
+ *   { credentials: {}, oauth: { accessToken: 'ya29...', ... } }
+ *
+ * For mixed (future: OAuth + user-provided extras):
+ *   { credentials: { webhookSecret: '...' }, oauth: { accessToken: '...', ... } }
+ */
+export type AuthCredentials = {
+    /** User-provided credential values from the connection form. */
+    credentials: Record<string, string>;
+    /** OAuth token data. Present when auth.type is "managed". */
+    oauth?: OAuthCredentials;
+};
+export type AuthModule = {
+    /**
+     * Get all authentication data for this plugin installation.
+     *
+     * Returns user-provided credentials (API keys, tokens from the
+     * connection form) and, for managed OAuth providers, a current
+     * access token that the SDK keeps refreshed.
+     *
+     * This is safe to call repeatedly — the SDK caches internally.
+     */
+    get: () => Promise<AuthCredentials>;
+};
+export declare function createAuthModule(api: ApiClient): AuthModule;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B,gCAAgC;IAChC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,gBAAgB,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;OAQG;IACH,GAAG,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;CACpC,CAAA;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,UAAU,CAyB3D"}

package/dist/auth.js

@@ -0,0 +1,45 @@
+/**
+ * Auth Module
+ *
+ * Unified interface for all authentication credentials.
+ * `mission.auth.get()` returns a single object containing:
+ *  - User-provided credentials (API keys, tokens, secrets from the connection form)
+ *  - OAuth token data (for managed auth providers like Google, Slack)
+ *
+ * Plugin authors always call `auth.get()` regardless of auth type.
+ *
+ * For managed auth (Nango-backed), the SDK caches tokens and refreshes
+ * transparently. See docs/technical-designs/managed-auth-nango.md.
+ *
+ * For custom auth, credentials are collected via a connection form
+ * defined in mission.json's `auth.credentials` schema.
+ *
+ * Transport: tRPC mutation/query via Mission gateway API.
+ */
+// ─── Factory ─────────────────────────────────────────────────────────────────
+export function createAuthModule(api) {
+    // Cache for managed OAuth tokens
+    let cachedAuth = null;
+    const CACHE_TTL_MS = 4 * 60 * 1000; // Refresh 4 min before typical 1h expiry
+    function isCacheValid() {
+        if (!cachedAuth)
+            return false;
+        // If there's no OAuth component, credentials are static — cache forever
+        if (!cachedAuth.data.oauth)
+            return true;
+        // If there is OAuth, check if the token is still fresh
+        const elapsed = Date.now() - cachedAuth.fetchedAt;
+        return elapsed < CACHE_TTL_MS;
+    }
+    return {
+        get: async () => {
+            if (isCacheValid()) {
+                return cachedAuth.data;
+            }
+            const auth = (await api.trpc.plugin.getAuth.query({}));
+            cachedAuth = { data: auth, fetchedAt: Date.now() };
+            return auth;
+        }
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqDH,gFAAgF;AAEhF,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC7C,iCAAiC;IACjC,IAAI,UAAU,GAAwD,IAAI,CAAA;IAC1E,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,yCAAyC;IAE5E,SAAS,YAAY;QACnB,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAA;QAC7B,wEAAwE;QACxE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QACvC,uDAAuD;QACvD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,SAAS,CAAA;QACjD,OAAO,OAAO,GAAG,YAAY,CAAA;IAC/B,CAAC;IAED,OAAO;QACL,GAAG,EAAE,KAAK,IAA8B,EAAE;YACxC,IAAI,YAAY,EAAE,EAAE,CAAC;gBACnB,OAAO,UAAW,CAAC,IAAI,CAAA;YACzB,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAoB,CAAA;YACzE,UAAU,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;YAClD,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Config Module
+ *
+ * Fetches per-installation configuration from the control plane.
+ * Accepts optional defaults so plugins always get a complete config
+ * object without manual merging.
+ *
+ * The control plane stores config per AppConnection. Values are set
+ * by the user in the App's settings UI (defined by configSchema in
+ * mission.json). The SDK merges platform values over provided defaults
+ * so the returned object is always complete.
+ *
+ * Transport: tRPC query via Mission gateway API.
+ *
+ * See docs/product/apps.md § App configuration state.
+ */
+import type { ApiClient } from './api';
+export type ConfigModule = {
+    /**
+     * Fetch the full configuration object for this plugin installation.
+     *
+     * If `defaults` are provided, the SDK merges platform-stored values
+     * over them, so the result is always a complete `T` with no undefined
+     * fields. Without defaults, returns whatever the platform has stored.
+     *
+     * @example
+     * ```ts
+     * const config = await mission.config.get<GmailConfig>({
+     *   watchLabels: ['INBOX'],
+     *   maxResults: 20,
+     *   signatureLine: ''
+     * })
+     * // config is guaranteed to have all three fields
+     * ```
+     */
+    get: <T = Record<string, unknown>>(defaults?: Partial<T>) => Promise<T>;
+};
+export declare function createConfigModule(api: ApiClient): ConfigModule;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CACxE,CAAA;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY,CAgB/D"}

package/dist/config.js

@@ -0,0 +1,28 @@
+/**
+ * Config Module
+ *
+ * Fetches per-installation configuration from the control plane.
+ * Accepts optional defaults so plugins always get a complete config
+ * object without manual merging.
+ *
+ * The control plane stores config per AppConnection. Values are set
+ * by the user in the App's settings UI (defined by configSchema in
+ * mission.json). The SDK merges platform values over provided defaults
+ * so the returned object is always complete.
+ *
+ * Transport: tRPC query via Mission gateway API.
+ *
+ * See docs/product/apps.md § App configuration state.
+ */
+export function createConfigModule(api) {
+    return {
+        get: async (defaults) => {
+            const platformValues = (await api.trpc.plugin.getConfig.query({}));
+            if (defaults) {
+                return { ...defaults, ...platformValues };
+            }
+            return platformValues;
+        }
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAyBH,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAC/C,OAAO;QACL,GAAG,EAAE,KAAK,EACR,QAAqB,EACT,EAAE;YACd,MAAM,cAAc,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAC3D,EAAE,CACH,CAAe,CAAA;YAEhB,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,cAAc,EAAO,CAAA;YAChD,CAAC;YAED,OAAO,cAAmB,CAAA;QAC5B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Plugin Context
+ *
+ * Bootstrapped from environment variables injected by the Mission control plane
+ * when it starts the plugin process inside the Daytona sandbox.
+ *
+ * See docs/technical-designs/plugin-architecture.md §4.5.
+ */
+export type PluginContext = {
+    /** Mission control plane API base URL. */
+    apiUrl: string;
+    /** JWT scoped to this plugin installation (for outbound API calls). */
+    pluginToken: string;
+    /** Stable identifier for this plugin installation (per-workspace). */
+    installationId: string;
+    /** Port assigned by the control plane for this plugin's HTTP server. */
+    pluginPort: number;
+};
+/**
+ * Read plugin context from process environment variables.
+ * These are injected by the Mission control plane when starting the plugin.
+ */
+export declare function readContextFromEnv(): PluginContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAQlD"}

package/dist/context.js

@@ -0,0 +1,22 @@
+/**
+ * Plugin Context
+ *
+ * Bootstrapped from environment variables injected by the Mission control plane
+ * when it starts the plugin process inside the Daytona sandbox.
+ *
+ * See docs/technical-designs/plugin-architecture.md §4.5.
+ */
+/**
+ * Read plugin context from process environment variables.
+ * These are injected by the Mission control plane when starting the plugin.
+ */
+export function readContextFromEnv() {
+    const portStr = process.env.MISSION_PLUGIN_PORT;
+    return {
+        apiUrl: process.env.MISSION_API_URL ?? 'http://localhost:8665',
+        pluginToken: process.env.MISSION_PLUGIN_TOKEN ?? '',
+        installationId: process.env.MISSION_INSTALLATION_ID ?? '',
+        pluginPort: portStr ? Number.parseInt(portStr, 10) : 3000
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAA;IAC/C,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,uBAAuB;QAC9D,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE;QACnD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE;QACzD,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;KAC1D,CAAA;AACH,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Events Module
+ *
+ * Plugins send messages to the agent when external events occur.
+ * This is the ONLY event type plugins emit — there are no domain-specific
+ * event types (no 'gmail.push_notification', no 'sentry.issue.created').
+ *
+ * The plugin's job is to:
+ *   1. Receive external data (webhooks, streams) via ingress
+ *   2. Process and interpret that data
+ *   3. Tell the agent what happened and what to do about it
+ *
+ * The platform routes the message to the appropriate agent(s) based
+ * on the plugin's App configuration and the workspace's agent routing.
+ *
+ * Transport: tRPC mutation via Mission gateway API.
+ *
+ * See docs/product/apps.md § Communication model → Events.
+ */
+import type { ApiClient } from './api';
+/**
+ * A message from a plugin to the agent.
+ *
+ * Plugins process their domain-specific inbound data and produce
+ * human-readable messages that agents can reason about.
+ */
+export type AgentMessage = {
+    /**
+     * Human-readable message describing what happened.
+     * This is what the agent sees and reasons about.
+     *
+     * @example "New email from john@example.com: \"Q3 Report Review\" — requesting approval on budget figures."
+     * @example "Sentry alert: TypeError in auth.ts — 47 events in the last hour affecting 12 users."
+     * @example "Inbound phone call from +1-555-0123. Caller is asking about order status."
+     */
+    message: string;
+    /**
+     * Structured context data the agent can reference.
+     * Include IDs, metadata, and any data that helps the agent
+     * take follow-up actions using the plugin's tools.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Optional deduplication key to prevent duplicate processing.
+     * If the platform has already processed a message with this key,
+     * it will be silently dropped.
+     */
+    deduplicationKey?: string;
+};
+export type EventsModule = {
+    /**
+     * Send a message to the agent about an external event.
+     *
+     * The platform routes it to the appropriate agent(s) based on
+     * the workspace's routing configuration.
+     *
+     * Fire-and-forget — the API handles delivery.
+     */
+    send: (message: AgentMessage) => Promise<void>;
+};
+export declare function createEventsModule(api: ApiClient): EventsModule;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;OAOG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C,CAAA;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY,CAQ/D"}

package/dist/events.js

@@ -0,0 +1,30 @@
+/**
+ * Events Module
+ *
+ * Plugins send messages to the agent when external events occur.
+ * This is the ONLY event type plugins emit — there are no domain-specific
+ * event types (no 'gmail.push_notification', no 'sentry.issue.created').
+ *
+ * The plugin's job is to:
+ *   1. Receive external data (webhooks, streams) via ingress
+ *   2. Process and interpret that data
+ *   3. Tell the agent what happened and what to do about it
+ *
+ * The platform routes the message to the appropriate agent(s) based
+ * on the plugin's App configuration and the workspace's agent routing.
+ *
+ * Transport: tRPC mutation via Mission gateway API.
+ *
+ * See docs/product/apps.md § Communication model → Events.
+ */
+// ─── Factory ─────────────────────────────────────────────────────────────────
+export function createEventsModule(api) {
+    return {
+        send: async (message) => {
+            void api.trpc.plugin.sendEvent.mutate(message).catch((err) => {
+                console.error('[Events] send failed:', err);
+            });
+        }
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkDH,gFAAgF;AAEhF,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAC/C,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,OAAqB,EAAiB,EAAE;YACnD,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACpE,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAA;YAC7C,CAAC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/http-server.d.ts

@@ -0,0 +1,51 @@
+/**
+ * HTTP Server
+ *
+ * Internal HTTP server that runs inside the plugin's Daytona sandbox.
+ * This is the inbound entrypoint for all traffic to the plugin:
+ *
+ *   Mission API → Daytona Preview URL → this server:
+ *     POST /_mission/tools/:toolName   — tool call dispatch
+ *     GET  /_mission/health            — health check
+ *     GET  /_mission/ping              — keep-alive ping (resets Daytona auto-stop)
+ *
+ *   External services → Daytona Signed Preview URL → this server:
+ *     POST /{ingressPath}              — webhook delivery
+ *     GET  /{ingressPath} (ws upgrade) — WebSocket stream (e.g., Twilio media)
+ *
+ * The server is started by mission.connect() and stopped during graceful shutdown.
+ * Plugin authors never interact with it directly — they register tool handlers
+ * and ingress handlers through the SDK, and this server routes to them.
+ *
+ * See docs/technical-designs/plugin-architecture.md §4.1.
+ * See docs/technical-designs/daytona-sandbox-runtime.md §2-3.
+ */
+import * as http from 'node:http';
+export type RouteHandler = (req: ParsedRequest) => Promise<{
+    status: number;
+    headers?: Record<string, string>;
+    body?: string;
+}>;
+export type ParsedRequest = {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+    query: Record<string, string>;
+    /** The matched route parameter, e.g., the tool name from /_mission/tools/:name */
+    params: Record<string, string>;
+};
+export type PluginHttpServer = {
+    /** Start listening on the given port. */
+    start: (port: number) => Promise<void>;
+    /** Stop the server gracefully. */
+    stop: () => Promise<void>;
+    /** Register a route handler. Supports simple patterns like /_mission/tools/:name */
+    route: (method: string, pattern: string, handler: RouteHandler) => void;
+    /** The underlying Node HTTP server (for WebSocket upgrades if needed). */
+    server: http.Server | null;
+    /** The port the server is listening on. */
+    port: number;
+};
+export declare function createHttpServer(): PluginHttpServer;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAIjC,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAC,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yCAAyC;IACzC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,kCAAkC;IAClC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;IACvE,0EAA0E;IAC1E,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IAC1B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAmED,wBAAgB,gBAAgB,IAAI,gBAAgB,CAwGnD"}

package/dist/http-server.js

@@ -0,0 +1,163 @@
+/**
+ * HTTP Server
+ *
+ * Internal HTTP server that runs inside the plugin's Daytona sandbox.
+ * This is the inbound entrypoint for all traffic to the plugin:
+ *
+ *   Mission API → Daytona Preview URL → this server:
+ *     POST /_mission/tools/:toolName   — tool call dispatch
+ *     GET  /_mission/health            — health check
+ *     GET  /_mission/ping              — keep-alive ping (resets Daytona auto-stop)
+ *
+ *   External services → Daytona Signed Preview URL → this server:
+ *     POST /{ingressPath}              — webhook delivery
+ *     GET  /{ingressPath} (ws upgrade) — WebSocket stream (e.g., Twilio media)
+ *
+ * The server is started by mission.connect() and stopped during graceful shutdown.
+ * Plugin authors never interact with it directly — they register tool handlers
+ * and ingress handlers through the SDK, and this server routes to them.
+ *
+ * See docs/technical-designs/plugin-architecture.md §4.1.
+ * See docs/technical-designs/daytona-sandbox-runtime.md §2-3.
+ */
+import * as http from 'node:http';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function parseQueryString(qs) {
+    const params = {};
+    if (!qs)
+        return params;
+    for (const pair of qs.split('&')) {
+        const [key, value] = pair.split('=');
+        if (key) {
+            params[decodeURIComponent(key)] = decodeURIComponent(value ?? '');
+        }
+    }
+    return params;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+function matchRoute(routes, method, path) {
+    const pathSegments = path.split('/').filter(Boolean);
+    for (const route of routes) {
+        if (route.method !== method && route.method !== '*')
+            continue;
+        const routeSegments = route.segments;
+        if (routeSegments.length !== pathSegments.length)
+            continue;
+        const params = {};
+        let match = true;
+        for (let i = 0; i < routeSegments.length; i++) {
+            const routeSeg = routeSegments[i];
+            const pathSeg = pathSegments[i];
+            if (routeSeg.startsWith(':')) {
+                params[routeSeg.slice(1)] = pathSeg;
+            }
+            else if (routeSeg !== pathSeg) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return { route, params };
+    }
+    return null;
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+export function createHttpServer() {
+    const routes = [];
+    let server = null;
+    let _listenPort = 0;
+    const pluginServer = {
+        server: null,
+        port: 0,
+        route(method, pattern, handler) {
+            routes.push({
+                method: method.toUpperCase(),
+                pattern,
+                segments: pattern.split('/').filter(Boolean),
+                handler
+            });
+        },
+        start(port) {
+            return new Promise((resolve, reject) => {
+                server = http.createServer(async (req, res) => {
+                    const urlParts = (req.url ?? '/').split('?');
+                    const path = urlParts[0];
+                    const queryString = urlParts[1] ?? '';
+                    const method = (req.method ?? 'GET').toUpperCase();
+                    const matched = matchRoute(routes, method, path);
+                    if (!matched) {
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Not found', path }));
+                        return;
+                    }
+                    try {
+                        const body = await readBody(req);
+                        const headers = {};
+                        for (const [key, value] of Object.entries(req.headers)) {
+                            if (typeof value === 'string') {
+                                headers[key.toLowerCase()] = value;
+                            }
+                        }
+                        const parsed = {
+                            method,
+                            path,
+                            headers,
+                            body,
+                            query: parseQueryString(queryString),
+                            params: matched.params
+                        };
+                        const result = await matched.route.handler(parsed);
+                        const responseHeaders = {
+                            'Content-Type': 'application/json',
+                            ...(result.headers ?? {})
+                        };
+                        res.writeHead(result.status, responseHeaders);
+                        res.end(result.body ?? '');
+                    }
+                    catch (err) {
+                        console.error('[HttpServer] Handler error:', err);
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            error: 'Internal server error',
+                            message: err instanceof Error ? err.message : String(err)
+                        }));
+                    }
+                });
+                server.on('error', reject);
+                server.listen(port, () => {
+                    _listenPort = port;
+                    pluginServer.server = server;
+                    pluginServer.port = port;
+                    console.error(`[HttpServer] Listening on port ${port}`);
+                    resolve();
+                });
+            });
+        },
+        stop() {
+            return new Promise((resolve, reject) => {
+                if (!server) {
+                    resolve();
+                    return;
+                }
+                server.close(err => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        console.error('[HttpServer] Server stopped');
+                        resolve();
+                    }
+                });
+            });
+        }
+    };
+    return pluginServer;
+}
+//# sourceMappingURL=http-server.js.map

package/dist/http-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.js","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAiCjC,gFAAgF;AAEhF,SAAS,gBAAgB,CAAC,EAAU;IAClC,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,IAAI,CAAC,EAAE;QAAE,OAAO,MAAM,CAAA;IACtB,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACpC,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,GAAG,kBAAkB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;QACnE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,GAAyB;IACzC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACrD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QACrE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACzB,CAAC,CAAC,CAAA;AACJ,CAAC;AASD,SAAS,UAAU,CACjB,MAAe,EACf,MAAc,EACd,IAAY;IAEZ,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAEpD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG;YAAE,SAAQ;QAE7D,MAAM,aAAa,GAAG,KAAK,CAAC,QAAQ,CAAA;QACpC,IAAI,aAAa,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM;YAAE,SAAQ;QAE1D,MAAM,MAAM,GAA2B,EAAE,CAAA;QACzC,IAAI,KAAK,GAAG,IAAI,CAAA;QAEhB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9C,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;YACjC,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAAA;YAC/B,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAA;YACrC,CAAC;iBAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;gBAChC,KAAK,GAAG,KAAK,CAAA;gBACb,MAAK;YACP,CAAC;QACH,CAAC;QAED,IAAI,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;IACrC,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,gFAAgF;AAEhF,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAY,EAAE,CAAA;IAC1B,IAAI,MAAM,GAAuB,IAAI,CAAA;IACrC,IAAI,WAAW,GAAG,CAAC,CAAA;IAEnB,MAAM,YAAY,GAAqB;QACrC,MAAM,EAAE,IAAI;QACZ,IAAI,EAAE,CAAC;QAEP,KAAK,CAAC,MAAc,EAAE,OAAe,EAAE,OAAqB;YAC1D,MAAM,CAAC,IAAI,CAAC;gBACV,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE;gBAC5B,OAAO;gBACP,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;gBAC5C,OAAO;aACR,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,IAAY;YAChB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;oBAC5C,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;oBAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;oBACxB,MAAM,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;oBACrC,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;oBAElD,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;oBAEhD,IAAI,CAAC,OAAO,EAAE,CAAC;wBACb,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAA;wBAC1D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;wBACrD,OAAM;oBACR,CAAC;oBAED,IAAI,CAAC;wBACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAA;wBAChC,MAAM,OAAO,GAA2B,EAAE,CAAA;wBAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;4BACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gCAC9B,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAA;4BACpC,CAAC;wBACH,CAAC;wBAED,MAAM,MAAM,GAAkB;4BAC5B,MAAM;4BACN,IAAI;4BACJ,OAAO;4BACP,IAAI;4BACJ,KAAK,EAAE,gBAAgB,CAAC,WAAW,CAAC;4BACpC,MAAM,EAAE,OAAO,CAAC,MAAM;yBACvB,CAAA;wBAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;wBAElD,MAAM,eAAe,GAA2B;4BAC9C,cAAc,EAAE,kBAAkB;4BAClC,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;yBAC1B,CAAA;wBAED,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;wBAC7C,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;oBAC5B,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAA;wBACjD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAA;wBAC1D,GAAG,CAAC,GAAG,CACL,IAAI,CAAC,SAAS,CAAC;4BACb,KAAK,EAAE,uBAAuB;4BAC9B,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;yBAC1D,CAAC,CACH,CAAA;oBACH,CAAC;gBACH,CAAC,CAAC,CAAA;gBAEF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;gBAE1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;oBACvB,WAAW,GAAG,IAAI,CAAA;oBAClB,YAAY,CAAC,MAAM,GAAG,MAAM,CAAA;oBAC5B,YAAY,CAAC,IAAI,GAAG,IAAI,CAAA;oBACxB,OAAO,CAAC,KAAK,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAA;oBACvD,OAAO,EAAE,CAAA;gBACX,CAAC,CAAC,CAAA;YACJ,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,IAAI;YACF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,OAAO,EAAE,CAAA;oBACT,OAAM;gBACR,CAAC;gBACD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;oBACjB,IAAI,GAAG,EAAE,CAAC;wBACR,MAAM,CAAC,GAAG,CAAC,CAAA;oBACb,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAA;wBAC5C,OAAO,EAAE,CAAA;oBACX,CAAC;gBACH,CAAC,CAAC,CAAA;YACJ,CAAC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;IAED,OAAO,YAAY,CAAA;AACrB,CAAC"}