| 39 | // the OAuth start flow. These strings are read by the agent resolving the |
| 40 | // failure, so they must name tools that actually exist on the executor. |
| 41 | const authRecovery = (code: AuthToolFailureCode, input?: AuthToolFailureInput["recovery"]) => { |
| 42 | // A scope-insufficient rejection cannot be fixed by re-running the same |
| 43 | // grant, so this branch deliberately omits startOAuthTool/oauthInstructions: |
| 44 | // an agent following the hints would loop through an identical consent and |
| 45 | // land on the identical 403. The connection must be reconnected with a |
| 46 | // broader scope, which is a user decision, not a retryable tool call. |
| 47 | if (code === "oauth_scope_insufficient") { |
| 48 | return { |
| 49 | listConnectionsTool: "executor.coreTools.connections.list", |
| 50 | ...(input?.configureIntegrationTool |
| 51 | ? { configureIntegrationTool: input.configureIntegrationTool } |
| 52 | : {}), |
| 53 | scopeInstructions: |
| 54 | "The connection's OAuth grant does not cover the scope this operation requires; re-authenticating with the same grant will return the same error. Tell the user which operation was denied and ask them to reconnect the integration with broader access (or use a connection that already has it). Call listConnectionsTool to see the available connections and their scopes.", |
| 55 | }; |
| 56 | } |
| 57 | return { |
| 58 | createConnectionTool: "executor.coreTools.connections.createHandoff", |
| 59 | startOAuthTool: "executor.coreTools.oauth.start", |
| 60 | listConnectionsTool: "executor.coreTools.connections.list", |
| 61 | ...(input?.configureIntegrationTool |
| 62 | ? { configureIntegrationTool: input.configureIntegrationTool } |
| 63 | : {}), |
| 64 | connectionInstructions: |
| 65 | "For API keys and tokens, call createConnectionTool for the integration to get a browser URL; the user enters the credential there, which creates the bound connection. Do not ask the user to paste secrets into chat. Then call listConnectionsTool to confirm the connection exists before retrying this tool.", |
| 66 | oauthInstructions: |
| 67 | "For OAuth credentials, call startOAuthTool and give the returned authorizationUrl to the user. The completed connection binds automatically, then retry the tool.", |
| 68 | }; |
| 69 | }; |
| 70 | |
| 71 | export const authToolFailure = <T = never>(input: AuthToolFailureInput): ToolResult<T> => { |
| 72 | const error: ToolError = { |