@mastra/connect 1.3.1-alpha.1 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,4 @@
1
+ import { z } from 'zod';
1
2
  import type { IntegrationCatalogEntry, ProjectConnection } from './client.js';
2
3
  /**
3
4
  * Record key of the built-in connect-prompt tool. Reserved: a provider tool
@@ -28,7 +29,27 @@ export interface ConnectPromptPayload {
28
29
  /** Echoed when the agent asked for one specific provider and it is connectable. */
29
30
  requestedProvider?: string;
30
31
  providers: ConnectPromptProvider[];
32
+ /** Outcome for the model once a paused prompt resumes, e.g. "Linear connected successfully." */
33
+ message?: string;
34
+ /** Why the connection failed, as the chat UI reported it, when a paused prompt resumes without one. */
35
+ error?: string;
31
36
  }
37
+ /**
38
+ * What a chat UI resumes a paused `request_connection` call with once the
39
+ * user's connection settles: `active`, or `failed` with the reason the UI saw
40
+ * (closed window, rejected credentials, connection limit). The tool re-checks
41
+ * the platform rather than trusting it, so a stale or forged resume can't
42
+ * report a false success, and a failure that raced a success reports success.
43
+ */
44
+ export declare const connectPromptResumeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
45
+ provider: z.ZodString;
46
+ status: z.ZodLiteral<"active">;
47
+ }, z.core.$strip>, z.ZodObject<{
48
+ provider: z.ZodString;
49
+ status: z.ZodLiteral<"failed">;
50
+ error: z.ZodString;
51
+ }, z.core.$strip>], "status">;
52
+ export type ConnectPromptResume = z.infer<typeof connectPromptResumeSchema>;
32
53
  export interface ConnectPromptInputs {
33
54
  catalog: IntegrationCatalogEntry[];
34
55
  connections: ProjectConnection[];
@@ -54,5 +75,19 @@ export declare function buildConnectPromptTool({ loadInputs, resourceId, }: {
54
75
  resourceId: string;
55
76
  }): import("@mastra/core/tools").Tool<{
56
77
  provider?: string | undefined;
57
- }, unknown, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, "request_connection", unknown>;
78
+ }, unknown, unknown, {
79
+ provider: string;
80
+ status: "active";
81
+ } | {
82
+ provider: string;
83
+ status: "failed";
84
+ error: string;
85
+ }, import("@mastra/core/tools").ToolExecutionContext<unknown, {
86
+ provider: string;
87
+ status: "active";
88
+ } | {
89
+ provider: string;
90
+ status: "failed";
91
+ error: string;
92
+ }, unknown>, "request_connection", unknown>;
58
93
  //# sourceMappingURL=connect-prompt-tool.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"connect-prompt-tool.d.ts","sourceRoot":"","sources":["../src/connect-prompt-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC;IACtE,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;IACnB,0FAA0F;IAC1F,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,qBAAqB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,6EAA6E;IAC7E,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,UAAU,EACV,UAAU,GACX,EAAE;IACD,UAAU,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;;2IAkDA"}
1
+ {"version":3,"file":"connect-prompt-tool.d.ts","sourceRoot":"","sources":["../src/connect-prompt-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,UAAU,EAAE,WAAW,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC;IACtE,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;IACnB,0FAA0F;IAC1F,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uGAAuG;IACvG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;6BAGpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,6EAA6E;IAC7E,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,UAAU,EACV,UAAU,GACX,EAAE;IACD,UAAU,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;;;;;;;;;;;;;;;;4CA0EA"}
package/dist/index.cjs CHANGED
@@ -684,6 +684,21 @@ async function disconnectConnection(client, connectionId) {
684
684
  */
685
685
  const CONNECT_PROMPT_TOOL_KEY = "request_connection";
686
686
  /**
687
+ * What a chat UI resumes a paused `request_connection` call with once the
688
+ * user's connection settles: `active`, or `failed` with the reason the UI saw
689
+ * (closed window, rejected credentials, connection limit). The tool re-checks
690
+ * the platform rather than trusting it, so a stale or forged resume can't
691
+ * report a false success, and a failure that raced a success reports success.
692
+ */
693
+ const connectPromptResumeSchema = zod.z.discriminatedUnion("status", [zod.z.object({
694
+ provider: zod.z.string().min(1),
695
+ status: zod.z.literal("active")
696
+ }), zod.z.object({
697
+ provider: zod.z.string().min(1),
698
+ status: zod.z.literal("failed"),
699
+ error: zod.z.string().trim().min(1).max(500)
700
+ })]);
701
+ /**
687
702
  * Builds the built-in tool that lets an agent prompt the end user to connect
688
703
  * a provider account mid-conversation. Only added to resource-scoped
689
704
  * resolutions: without an end-user identity there is nobody to scope a new
@@ -700,9 +715,10 @@ const CONNECT_PROMPT_TOOL_KEY = "request_connection";
700
715
  function buildConnectPromptTool({ loadInputs, resourceId }) {
701
716
  return (0, _mastra_core_tools.createTool)({
702
717
  id: CONNECT_PROMPT_TOOL_KEY,
703
- description: "Ask the current user to connect a provider account (e.g. Linear, Slack). Call this when a task needs a provider whose tools are unavailable because no account is connected, or when the user asks to connect one. The result renders as a connect prompt in the UI — tell the user to use it, and do not fabricate links. Pass `provider` to request one specific provider; omit it to list everything the user can connect.",
718
+ description: "Ask the current user to connect a provider account (e.g. Linear, Slack). Call this when a task needs a provider whose tools are unavailable because no account is connected, or when the user asks to connect one. Do not fabricate links. Pass `provider` to request one specific provider: the call renders a connect prompt in the UI and waits until the user connects, and its result then says whether the connection succeeded or why it failed. Omit `provider` to list everything the user can connect without waiting; an unknown provider also returns that list.",
704
719
  inputSchema: zod.z.object({ provider: zod.z.string().optional().describe("Provider id to request (e.g. \"linear\"). Omit to list all connectable providers.") }),
705
- execute: async (input) => {
720
+ resumeSchema: connectPromptResumeSchema,
721
+ execute: async (input, context) => {
706
722
  const { catalog, connections, allowlist } = await loadInputs();
707
723
  const allow = allowlist === void 0 ? void 0 : new Set(Array.from(allowlist, (id) => id.toLowerCase()));
708
724
  const connectable = catalog.filter((entry) => allow === void 0 || allow.has(entry.id.toLowerCase()));
@@ -721,15 +737,36 @@ function buildConnectPromptTool({ loadInputs, resourceId }) {
721
737
  };
722
738
  const requestedId = input.provider?.toLowerCase();
723
739
  const requested = requestedId === void 0 ? void 0 : connectable.find((entry) => entry.id.toLowerCase() === requestedId);
724
- if (requested) return {
740
+ const payload = requested ? {
725
741
  type: "connect-prompt",
726
742
  requestedProvider: requested.id,
727
743
  providers: [toProvider(requested)]
728
- };
729
- return {
744
+ } : {
730
745
  type: "connect-prompt",
731
746
  providers: connectable.map(toProvider)
732
747
  };
748
+ const agent = context?.agent;
749
+ const resumed = agent?.resumeData;
750
+ if (resumed) {
751
+ const provider = payload.providers.find((entry) => entry.id.toLowerCase() === resumed.provider.toLowerCase());
752
+ const name = provider?.displayName ?? resumed.provider;
753
+ if (provider?.connected) return {
754
+ ...payload,
755
+ message: `${name} connected successfully.`
756
+ };
757
+ if (resumed.status === "failed") return {
758
+ ...payload,
759
+ message: `${name} could not be connected: ${resumed.error}`,
760
+ error: resumed.error
761
+ };
762
+ return {
763
+ ...payload,
764
+ message: `${name} is not connected yet.`
765
+ };
766
+ }
767
+ if (!requested || payload.providers[0]?.connected) return payload;
768
+ if (agent?.suspend) await agent.suspend(payload);
769
+ return payload;
733
770
  }
734
771
  });
735
772
  }
@@ -85539,6 +85576,35 @@ function evictSharedStates(justAcquiredKey) {
85539
85576
  function scopeKey(resourceId) {
85540
85577
  return resourceId === void 0 ? GLOBAL_SCOPE_KEY : `resource:${resourceId}`;
85541
85578
  }
85579
+ /**
85580
+ * Tells the resolvers in `projectId` that a connection changed (activated, or
85581
+ * stopped being active or was removed), so the next resolution fetches fresh
85582
+ * instead of serving a snapshot that is wrong until its TTL runs out. A
85583
+ * change to `resourceId`'s own connection reaches that resource's scope; a
85584
+ * global connection (no `resourceId`) appears in every scope, so it reaches
85585
+ * all of them. The end-user connect routes call this when they observe the
85586
+ * change. A settled snapshot that already agrees is left alone, and so is a
85587
+ * fetch that started after the same change was reported, so repeated status
85588
+ * polls cost nothing.
85589
+ */
85590
+ function invalidateConnection({ projectId, resourceId, connectionId, active }) {
85591
+ for (const state of sharedStates.values()) {
85592
+ if (state.projectId !== projectId) continue;
85593
+ const scopes = resourceId === void 0 ? Array.from(state.scopes.values()) : [state.scopes.get(scopeKey(resourceId))];
85594
+ for (const scope of scopes) {
85595
+ if (!scope) continue;
85596
+ if (scope.inflight) {
85597
+ const reported = scope.reported.get(connectionId);
85598
+ if (reported?.active === active && (scope.inflightFetch ?? 0) > reported.afterFetch) continue;
85599
+ } else if (scope.cache?.activeConnectionIds.has(connectionId) === active) continue;
85600
+ scope.generation += 1;
85601
+ scope.reported.set(connectionId, {
85602
+ active,
85603
+ afterFetch: scope.fetches
85604
+ });
85605
+ }
85606
+ }
85607
+ }
85542
85608
  /** Gets or creates the scope for a resource key, touching its LRU clock. */
85543
85609
  function acquireScope(state, resourceId) {
85544
85610
  const key = scopeKey(resourceId);
@@ -85551,6 +85617,9 @@ function acquireScope(state, resourceId) {
85551
85617
  projectId: state.projectId,
85552
85618
  ...resourceId === void 0 ? {} : { resourceId }
85553
85619
  }),
85620
+ generation: 0,
85621
+ fetches: 0,
85622
+ reported: /* @__PURE__ */ new Map(),
85554
85623
  lastUsedAt: Date.now()
85555
85624
  };
85556
85625
  state.scopes.set(key, scope);
@@ -85651,44 +85720,70 @@ async function loadConnectPromptInputs(state, client) {
85651
85720
  */
85652
85721
  function refreshScope(state, scope) {
85653
85722
  if (state.closing) return state.closing.then(() => refreshScope(state, acquireScope(state, scope.resourceId)));
85654
- if (!scope.inflight) scope.inflight = (async () => {
85655
- try {
85656
- const { connections, catalog, catalogAvailable } = await loadSnapshotInputs(state, scope.client);
85657
- const requests = buildRequests(state.normalizedProviders, catalog, catalogAvailable);
85658
- const clientOptions = {
85659
- ...state.options.client,
85660
- projectId: state.projectId,
85661
- ...scope.resourceId === void 0 ? {} : { resourceId: scope.resourceId }
85662
- };
85663
- const { record, mcpKeys } = await mapTools(connections, requests, state.options, clientOptions, scope.client, state.mcpClients, state.resolverId);
85664
- if (scope.resourceId !== void 0 && state.options.connectPrompt !== false) {
85665
- if (record["request_connection"]) throw new MastraConnectConfigError(`Tool key '${CONNECT_PROMPT_TOOL_KEY}' is reserved for the built-in connect-prompt tool; a provider resolved a tool with the same key. Disable it with connectPrompt: false or exclude the conflicting provider tool.`);
85666
- const client = scope.client;
85667
- record[CONNECT_PROMPT_TOOL_KEY] = buildConnectPromptTool({
85668
- loadInputs: () => loadConnectPromptInputs(state, client),
85669
- resourceId: scope.resourceId
85670
- });
85723
+ if (!scope.inflight) {
85724
+ const generation = scope.generation;
85725
+ scope.inflightGeneration = generation;
85726
+ scope.fetches += 1;
85727
+ scope.inflightFetch = scope.fetches;
85728
+ scope.inflight = (async () => {
85729
+ try {
85730
+ const { connections, catalog, catalogAvailable } = await loadSnapshotInputs(state, scope.client);
85731
+ const requests = buildRequests(state.normalizedProviders, catalog, catalogAvailable);
85732
+ const clientOptions = {
85733
+ ...state.options.client,
85734
+ projectId: state.projectId,
85735
+ ...scope.resourceId === void 0 ? {} : { resourceId: scope.resourceId }
85736
+ };
85737
+ const { record, mcpKeys } = await mapTools(connections, requests, state.options, clientOptions, scope.client, state.mcpClients, state.resolverId);
85738
+ if (scope.resourceId !== void 0 && state.options.connectPrompt !== false) {
85739
+ if (record["request_connection"]) throw new MastraConnectConfigError(`Tool key '${CONNECT_PROMPT_TOOL_KEY}' is reserved for the built-in connect-prompt tool; a provider resolved a tool with the same key. Disable it with connectPrompt: false or exclude the conflicting provider tool.`);
85740
+ const client = scope.client;
85741
+ record[CONNECT_PROMPT_TOOL_KEY] = buildConnectPromptTool({
85742
+ loadInputs: () => loadConnectPromptInputs(state, client),
85743
+ resourceId: scope.resourceId
85744
+ });
85745
+ }
85746
+ scope.cache = {
85747
+ snapshot: record,
85748
+ fetchedAt: Date.now(),
85749
+ mcpKeys,
85750
+ activeConnectionIds: new Set(connections.filter((connection) => connection.status === "active").map((connection) => connection.id)),
85751
+ generation
85752
+ };
85753
+ scope.lastFailureAt = void 0;
85754
+ await pruneStaleMcpClients(state);
85755
+ return record;
85756
+ } catch (error) {
85757
+ scope.lastFailureAt = Date.now();
85758
+ throw error;
85759
+ } finally {
85760
+ scope.inflight = void 0;
85761
+ scope.inflightGeneration = void 0;
85762
+ scope.inflightFetch = void 0;
85671
85763
  }
85672
- scope.cache = {
85673
- snapshot: record,
85674
- fetchedAt: Date.now(),
85675
- mcpKeys
85676
- };
85677
- scope.lastFailureAt = void 0;
85678
- await pruneStaleMcpClients(state);
85679
- return record;
85680
- } catch (error) {
85681
- scope.lastFailureAt = Date.now();
85682
- throw error;
85683
- } finally {
85684
- scope.inflight = void 0;
85685
- }
85686
- })();
85764
+ })();
85765
+ }
85687
85766
  return scope.inflight;
85688
85767
  }
85768
+ /**
85769
+ * Refreshes a scope under its current generation: a fetch already in flight
85770
+ * from before an invalidation may have read the old connection list, so it
85771
+ * settles first and a new fetch starts.
85772
+ */
85773
+ async function refreshCurrentGeneration(state, scope) {
85774
+ if (scope.inflight && scope.inflightGeneration !== scope.generation) await scope.inflight.catch(() => {});
85775
+ return refreshScope(state, scope);
85776
+ }
85689
85777
  /** Serves a scope's snapshot: fresh from cache, stale with background revalidation, or a blocking first fetch. */
85690
85778
  async function resolveScope(state, resourceId) {
85691
85779
  const scope = acquireScope(state, resourceId);
85780
+ if (scope.cache && scope.cache.generation !== scope.generation) {
85781
+ const staleSnapshot = scope.cache.snapshot;
85782
+ return refreshCurrentGeneration(state, scope).catch((error) => {
85783
+ console.warn(`[@mastra/connect] Keeping cached tools after a connection change; platform refresh failed: ${error instanceof Error ? error.message : String(error)}`);
85784
+ return staleSnapshot;
85785
+ });
85786
+ }
85692
85787
  if (scope.cache && Date.now() - scope.cache.fetchedAt < state.ttlMs) return scope.cache.snapshot;
85693
85788
  if (scope.cache) {
85694
85789
  const staleSnapshot = scope.cache.snapshot;
@@ -86999,10 +87094,16 @@ function userConnectRoutes(options) {
86999
87094
  path: `${basePath}/connections/:id/status`,
87000
87095
  method: "GET",
87001
87096
  requiresAuth: true,
87002
- handler: gated(async (c, client) => {
87097
+ handler: gated(async (c, client, resourceId) => {
87003
87098
  const id = String(c.req.param("id") ?? "");
87004
87099
  const connection = (await listVisibleConnections(client)).find((candidate) => candidate.id === id);
87005
87100
  if (!connection) return notFound(c, "connection_not_found", "Connection not found.");
87101
+ if (connection.status !== "pending") invalidateConnection({
87102
+ projectId,
87103
+ ...connectionScope(connection) === "user" ? { resourceId } : {},
87104
+ connectionId: connection.id,
87105
+ active: connection.status === "active"
87106
+ });
87006
87107
  return c.json({
87007
87108
  id: connection.id,
87008
87109
  status: connection.status,
@@ -87014,7 +87115,7 @@ function userConnectRoutes(options) {
87014
87115
  path: `${basePath}/connections/:id`,
87015
87116
  method: "DELETE",
87016
87117
  requiresAuth: true,
87017
- handler: gated(async (c, client) => {
87118
+ handler: gated(async (c, client, resourceId) => {
87018
87119
  const id = String(c.req.param("id") ?? "");
87019
87120
  const connection = (await listVisibleConnections(client)).find((candidate) => candidate.id === id);
87020
87121
  if (!connection) return notFound(c, "connection_not_found", "Connection not found.");
@@ -87024,6 +87125,12 @@ function userConnectRoutes(options) {
87024
87125
  message: "Global connections cannot be disconnected from the end-user surface."
87025
87126
  });
87026
87127
  await disconnectConnection(client, connection.id);
87128
+ invalidateConnection({
87129
+ projectId,
87130
+ resourceId,
87131
+ connectionId: connection.id,
87132
+ active: false
87133
+ });
87027
87134
  return c.body(null, 204);
87028
87135
  })
87029
87136
  },